diff --git a/.agents/skills/mcp-attribution-worktree b/.agents/skills/mcp-attribution-worktree deleted file mode 120000 index 78f1aa56..00000000 --- a/.agents/skills/mcp-attribution-worktree +++ /dev/null @@ -1 +0,0 @@ -../../skills/mcp-attribution-worktree \ No newline at end of file diff --git a/.agents/skills/mcp-attribution-worktree/SKILL.md b/.agents/skills/mcp-attribution-worktree/SKILL.md new file mode 100644 index 00000000..41839b8e --- /dev/null +++ b/.agents/skills/mcp-attribution-worktree/SKILL.md @@ -0,0 +1,139 @@ +--- +name: mcp-attribution-worktree +description: Triage, repair, and close MCP attribution issues from the local report API with evidence-driven decisions and isolated Worktrunk worktrees. Use this skill when Codex needs to process `tool` attribution issues and skills-related attribution issues, inspect related runs, decide whether the issue is actionable in `mcp/src` or `config/source/skills`, update attribution fields as `owner=codex`, and then complete the fix loop through GitHub issue tracking, worktree-based code changes, PR submission, and follow-up iteration when the problem is repairable. +--- + +# MCP Attribution Worktree + +Process MCP and skills-related attribution issues as an auditable maintenance workflow instead of ad-hoc debugging. + +## What this skill does + +Use this skill to: + +- fetch pending MCP and skills-related attribution issues from the local report API +- inspect issue detail plus representative runs before making any status decision +- map failures back to concrete `mcp/src` tools, `config/source/skills`, or classify them as environment / grader / duplicate noise +- update attribution issues with concise evidence, `owner=codex`, and links to external GitHub work +- isolate each actionable repair in its own Worktrunk worktree and branch +- carry actionable issues through repo repair and PR creation instead of stopping at issue state updates +- continue from existing GitHub issues or PRs when later review or evaluation feedback shows the first direction was incomplete or wrong +- run a real post-PR evaluation when an evaluation interface is available, and use that result to decide whether another repair loop is needed + +## Do not use this skill for + +- generic bug fixing without attribution evidence +- unrelated attribution categories that do not map to `mcp/src` or `config/source/skills` +- bulk repo changes unrelated to a specific attribution issue +- direct database or backend mutation outside the documented report API endpoints + +## Workflow + +1. Start with focused `tool` and `skill` backlog queries. +2. Process one issue at a time. Never mix evidence, notes, or worktrees across issues. +3. Run the existing-artifact preflight before choosing the representative run: read issue detail, current notes, existing `externalUrl`, and the state of any linked GitHub issue or PR. If a GitHub issue or PR already exists, treat it as part of the current state, not a finished endpoint. +4. Read at least one run's `result` and `trace`. Prefer to also read `evaluation-trace`. +5. Check the relevant implementation in `mcp/src` or `config/source/skills` before deciding whether the issue is actionable. +6. If the issue is actionable in repo code or skills content, do not stop at attribution triage. Open or link the matching GitHub issue, create a dedicated Worktrunk worktree, implement the fix, validate it, and prepare a PR. +7. If review comments, review decisions, or later evidence show the direction is wrong, start another focused iteration from the existing GitHub issue or PR context and continue improving instead of treating the first PR as final. +8. Update attribution fields through the report API after you have the right evidence, and update them again when the GitHub issue, PR, or evaluation result becomes available. +9. Before changing an attribution to `resolved`, run a closure preflight on the linked GitHub artifact again: reread the latest PR comments, review comments, review decisions, and issue comments after the most recent code push or evaluation result. +10. When a real evaluation interface exists, run a post-PR evaluation and use the result plus the closure preflight to decide whether to continue iterating or mark the issue closed. +11. Only stop after the issue is either clearly non-actionable or has been carried through the repair loop as far as the current environment allows. + +## Common requests + +- "Automatically process the pending MCP attribution issues." +- "Look at the tool and skills attribution backlog, fix the real issues, and update attribution with evidence." +- "Find valuable MCP attribution problems and fix them in isolated worktrees." +- "For each tool issue, decide whether it is a real `mcp/src` bug or just evaluation noise." +- "Continue iterating on the existing issue or PR after review comments." +- "After opening the PR, run a real evaluation and fix the next round if it still fails." + +## Routing + +| Task | Read | +| --- | --- | +| Run the report API triage flow and update attribution fields across tool and skills-related issues | `references/report-api-workflow.md` | +| Decide whether an issue is valuable and map it to `mcp/src` or `config/source/skills` | `references/value-triage.md` | +| Create GitHub issues, use Worktrunk, and repair the repo in isolation | `references/worktree-repair.md` | +| Continue from review feedback or real evaluation results after a PR already exists | `references/iteration-loop.md` | +| Trigger real evaluation runs and interpret the result | `references/evaluation-verification.md` | +| Dispatch one issue per worker and enforce closure-sweep rules in sub-agent prompts | `references/subagent-orchestration.md` | + +## Operating rules + +- Only update attribution issues through the local report API. +- Treat `owner` as fixed: always set it to `codex` when you patch an attribution. +- Before any new iteration, always inspect the latest attribution `notes`, `externalUrl`, linked GitHub issue or PR status, and any available PR comments or review decisions. +- Before moving any issue to `resolved`, always perform a fresh closure sweep on the linked issue or PR after the latest push or evaluation has completed. Do not rely on an earlier preflight. +- Do not change `resolutionStatus` until you have read at least one related run's `result` and `trace`. +- Do not mark an issue `resolved` without clear closure evidence such as an existing GitHub issue, PR, merged fix, or a verified duplicate that already has external tracking. +- Do not mark an issue `resolved` if there are unread or unaddressed PR comments, review comments, review decisions, or issue comments that arrived after the last time you inspected the linked artifact. +- Keep `notes` short but auditable. Include the representative run, the main failing signal, and the code or tool signal that supports the conclusion. +- If the evidence is incomplete, keep the issue `todo` or move it to `in_progress` and explicitly state what is still missing. +- For a real and repairable issue in `mcp/src` or `config/source/skills`, the default expectation is full follow-through: attribution triage, GitHub issue linkage, isolated worktree repair, validation, and PR creation. +- When the fix belongs to CloudBase skill content, edit `config/source/skills/` as the source of truth. Do not treat the root `skills/` directory as the source for those external skills. +- Only stop at status-only attribution updates when the issue is non-actionable, blocked by missing evidence, blocked by missing Worktrunk, or clearly outside MCP repo control. +- Do not use broad uncategorized backlog queries as the default source of work. Only use them in explicit fallback mode when category labels are incomplete or the user asks for a full backlog sweep. +- Items discovered through fallback broad queries must not enter the repair queue until run evidence clearly shows they belong to `mcp/src` or `config/source/skills`. +- Prefer one sub-agent per issue when sub-agent support exists. Give each sub-agent ownership of exactly one issue. If sub-agents are unavailable, process issues serially and keep a strict one-issue-at-a-time context. +- If a repair is needed, use Worktrunk's `wt` workflow for the isolated worktree. If `wt` is unavailable, stop and report that Worktrunk is missing instead of silently falling back to a shared checkout. +- Never reuse the same worktree for multiple attribution issues. +- Do not open or update GitHub issues until you have enough run evidence to explain the problem clearly. +- If an issue already has a GitHub issue or PR, read its current state before starting a new branch or changing direction: open or closed status, latest comments, review decisions, and whether the linked work is already stale or superseded. +- Review comments and post-PR evaluation failures are part of the same repair loop. Use them to drive another iteration instead of prematurely closing the attribution. +- If a real evaluation interface is available, prefer leaving the attribution `in_progress` until the repaired branch or PR passes a fresh evaluation round. +- Do not claim validation success from reasoning alone. Use the evaluation API and the final run result whenever that interface is available. + +## Required preflight + +Before starting a fresh diagnosis or code iteration for an attribution issue, complete this checklist in order: + +1. Read the attribution detail plus the latest `notes`. +2. Read `externalUrl` if present. +3. If `externalUrl` points to a GitHub issue, check whether it is open or closed and whether later comments changed the fix direction. +4. If `externalUrl` points to a PR, check whether it is open, merged, closed, or superseded. +5. Read PR comments, review comments, and review decisions before deciding whether to continue the same branch or start a new iteration. +6. Only after that, pick the representative run and continue into `result`, `trace`, and `evaluation-trace`. + +## Required closure preflight + +Before changing an attribution to `resolved`, complete this checklist in order even if you already did the normal preflight earlier: + +1. Reopen the linked GitHub issue or PR. +2. Re-read the latest top-level comments, review comments, and review decisions. +3. Confirm whether any comment arrived after the latest code push, PR update, or evaluation result. +4. If new feedback exists, keep the attribution `in_progress` and continue the loop. +5. Only if there is no newer unresolved feedback, evaluate whether closure evidence is now strong enough. + +## Quick commands + +```bash +curl -s 'http://127.0.0.1:5174/api/attributions?category=tool&resolutionStatus=todo&limit=50' +curl -s 'http://127.0.0.1:5174/api/attributions?category=skill&resolutionStatus=todo&limit=50' +curl -s "http://127.0.0.1:5174/api/attributions/" +curl -s "http://127.0.0.1:5174/api/runs///result" +curl -s "http://127.0.0.1:5174/api/runs///trace" +curl -s "http://127.0.0.1:5174/api/runs///evaluation-trace" +wt switch --create feature/attribution- +gh issue create --repo TencentCloudBase/CloudBase-MCP +gh pr view --comments --repo TencentCloudBase/CloudBase-MCP +gh pr create --repo TencentCloudBase/CloudBase-MCP +curl -s -X POST http://127.0.0.1:5174/api/evaluations +``` + +## Minimum self-check + +- Did I complete the existing-artifact preflight before starting a new diagnosis or code iteration? +- Did I inspect at least one related run's `result` and `trace` before changing status? +- Did I keep this issue isolated from every other issue? +- Is the issue actually actionable in `mcp/src`, `config/source/skills`, or is it environment / grader noise? +- If the issue was actionable, did I continue into GitHub issue / worktree / PR work instead of stopping at triage? +- If there was already a PR or review thread, did I continue from that feedback instead of ignoring it? +- If a real evaluation interface was available, did I run a fresh evaluation before treating the issue as closed? +- Did I base the validation conclusion on the final evaluation result instead of my own guess? +- If I patched the attribution, did I keep the change limited to `resolutionStatus`, `owner`, `notes`, and `externalUrl` when relevant? +- If I started a fix, does it live in its own Worktrunk worktree and branch? +- If I marked something `resolved`, is there explicit closure evidence? +- If I marked something `resolved`, did I re-read the latest PR comments, review comments, review decisions, and issue comments immediately before closing it? diff --git a/.agents/skills/mcp-attribution-worktree/references/evaluation-verification.md b/.agents/skills/mcp-attribution-worktree/references/evaluation-verification.md new file mode 100644 index 00000000..60ba44a7 --- /dev/null +++ b/.agents/skills/mcp-attribution-worktree/references/evaluation-verification.md @@ -0,0 +1,118 @@ +# Evaluation Verification + +## Purpose + +Use this reference when you need to verify that a proposed fix or repair direction actually works in a real evaluation run. + +## Core rule + +Do not treat implementation or static reasoning as proof of success. + +When the AI Coding Eval Report API is available, validation means: + +1. trigger a real evaluation run +2. wait for it to finish +3. read the final result +4. decide pass or fail from the returned run result + +## Required flow + +After you believe the implementation is ready: + +1. `POST /api/evaluations` +2. record `caseId` and `runId` +3. poll `GET /api/evaluations/{caseId}/{runId}` +4. once finished, read `GET /api/runs/{caseId}/{runId}/result` +5. optionally read `trace` and `evaluation-trace` if the run failed or is ambiguous + +Do not claim "validated" before step 4 is complete. + +## Required request shape + +The request body must include: + +- `caseId` +- `config` + +Typical config fields: + +- `mcp` +- `tcbCli` +- `skillsMode` +- `mcpPackage` +- `skillsRepo` +- `skillsRef` +- `skillsPath` +- `allInOneSkillsRepo` +- `allInOneSkillsRef` +- `allInOneSkillsLocalPath` +- `apiSkillsRepo` +- `apiSkillsRef` +- `apiSkillsPath` +- `agentType` +- `model` +- `evalModel` +- `maxTurns` +- `caseTimeoutSeconds` +- `evaluationTimeoutMs` + +## Local build expectations + +When local MCP code is under test: + +- build `mcp` first +- pass the absolute path to `mcp/dist/cli.cjs` as `config.mcpPackage` + +When `skillsMode=allinone` is under test: + +- build the local all-in-one skill bundle first +- pass the absolute bundle path as `config.allInOneSkillsLocalPath` + +## Result interpretation + +Use the final run result as the source of truth. + +### Pass + +Treat the evaluation as passed when: + +- `result.status == "pass"` +- and there is no failed test signal + +### Fail + +Treat the evaluation as failed when any of these are true: + +- `result.status == "fail"` +- `result.status == "error"` +- `result.status == "timeout"` +- `tests.failed > 0` +- `error` is present + +## Failure follow-up + +If the run fails: + +1. capture the failure summary +2. inspect `trace` and `evaluation-trace` +3. decide whether the problem is: + - still the same root cause + - a new regression + - environment noise +4. continue the repair loop if needed + +## Reporting format + +Every verification summary should include at least: + +- `caseId` +- `runId` +- evaluation status +- overall score when available +- tests passed / failed / total when available +- whether validation passed +- failure reason when it did not pass + +## Attribution rule + +If real evaluation is available, do not move a repairable issue to `resolved` until the final evaluation result supports closure or there is another explicit closure reason. diff --git a/.agents/skills/mcp-attribution-worktree/references/iteration-loop.md b/.agents/skills/mcp-attribution-worktree/references/iteration-loop.md new file mode 100644 index 00000000..d54c90dd --- /dev/null +++ b/.agents/skills/mcp-attribution-worktree/references/iteration-loop.md @@ -0,0 +1,123 @@ +# Iteration Loop + +## Purpose + +Use this reference when an attribution issue already has a linked GitHub issue or PR, or when a new review or evaluation result arrives after the first repair attempt. + +## Core rule + +Treat GitHub issues, PRs, review comments, and fresh evaluation results as part of the same repair loop. + +Do not assume that: + +- the first PR is final +- opening a PR is enough to mark the attribution closed +- an existing `externalUrl` means no more work is needed + +## Existing artifact first + +When an attribution already has `externalUrl` or notes pointing to previous work: + +1. Read that issue or PR first. +2. Capture its current state first: + - issue open or closed + - PR open, merged, closed, or superseded +3. Read comments, review comments, review decisions, and any follow-up discussion. +4. Compare that feedback with the latest attribution run evidence. +5. Decide whether to continue the same approach or redirect it. + +Do not start a new branch, worktree, or diagnosis pass until this check is complete. + +## Closure sweep + +Before you change an attribution from `in_progress` to `resolved`, repeat the artifact check one more time even if you already did it at the start of the iteration. + +You must re-read: + +1. the latest top-level PR comments +2. review comments +3. review decisions +4. linked issue comments when relevant + +Treat any newer unresolved feedback as a new iteration signal. Do not close the attribution off an older snapshot of the PR. + +## Continue vs restart + +### Continue the same PR + +Prefer continuing the same PR when: + +- review feedback asks for corrections, tightening, or missing edge cases +- the overall repair direction is still correct +- the next change is an iteration, not a different root-cause theory + +### Start a new iteration path + +Prefer a new worktree or branch when: + +- review or fresh evaluation shows the first direction was wrong +- the repair target moved from `mcp/src` to `config/source/skills`, or vice versa +- the PR became too mixed or too far from the new diagnosis +- the linked PR is closed, stale, or superseded and continuing it would hide the new root cause + +## Post-PR evaluation + +If a real evaluation interface exists: + +1. run a fresh evaluation after the PR or branch update +2. inspect the resulting run and failed checks +3. decide whether: + - the issue is now closed + - the issue needs another iteration + - the issue turned out to be grader or environment noise + +Use that new evaluation as stronger closure evidence than static reasoning alone. + +## Attribution state during iteration + +### Keep `in_progress` + +Keep the attribution `in_progress` while: + +- a PR exists but review feedback is unresolved +- a fresh evaluation still fails +- the next iteration is already clear + +### Move to `resolved` + +Move to `resolved` only when: + +- the PR or linked issue provides explicit closure +- and any available fresh evaluation no longer shows the original failure mode +- and the closure sweep found no newer unresolved PR comments, review comments, review decisions, or issue comments + +### Move to `invalid` + +Move to `invalid` when later review or evaluation shows: + +- the original attribution was wrong +- the real failure was environment or grader noise +- no repo or skill-source change is actually needed + +## Notes guidance + +When iterating, append evidence like this: + +```text +iteration=; prior=; new_signal=; conclusion= +``` + +This keeps the attribution auditable across multiple rounds. + +## Mandatory iteration checklist + +Before each new iteration: + +1. read attribution `notes` +2. read `externalUrl` +3. inspect linked issue or PR state +4. read comments and review decisions +5. decide continue vs restart +6. only then inspect the next representative run + +Before `resolved`, repeat steps 2-4 after the latest push or evaluation result so the closure decision is based on a fresh artifact read rather than an older preflight snapshot. diff --git a/.agents/skills/mcp-attribution-worktree/references/report-api-workflow.md b/.agents/skills/mcp-attribution-worktree/references/report-api-workflow.md new file mode 100644 index 00000000..aa294720 --- /dev/null +++ b/.agents/skills/mcp-attribution-worktree/references/report-api-workflow.md @@ -0,0 +1,258 @@ +# Report API Workflow + +## Purpose + +Use this reference to process MCP attribution issues through the local report API in a repeatable, auditable order, while treating attribution updates as one part of a larger repair loop rather than the final deliverable. + +## Allowed endpoints + +Use only these attribution endpoints for attribution state: + +- `GET /api/attributions` +- `GET /api/attributions/:issueId` +- `GET /api/runs/:caseId/:runId/result` +- `GET /api/runs/:caseId/:runId/trace` +- `GET /api/runs/:caseId/:runId/evaluation-trace` +- `PATCH /api/attributions/:issueId` + +Do not mutate attribution state through any other backend path. + +## Baseline query + +Start with: + +```text +GET /api/attributions?category=tool&resolutionStatus=todo&limit=50 +``` + +Then query explicit skills backlog too: + +```text +GET /api/attributions?category=skill&resolutionStatus=todo&limit=50 +``` + +Use the first query to get the focused MCP tool backlog. + +Use the second query to get explicitly labeled skills backlog. +Do not run a broad uncategorized backlog query by default. + +## Fallback query + +Only if category labeling looks incomplete, or if the user explicitly asks for a full todo sweep, run: + +```text +GET /api/attributions?resolutionStatus=todo&limit=100 +``` + +Use this broader query only to discover candidates that may have been miscategorized. + +Do not rely on the broad query as the default work source. + +## Per-issue sequence + +For each candidate issue: + +1. Read issue detail with `GET /api/attributions/:issueId`. +2. Review the current `notes` and `externalUrl`. +3. If there is already a linked GitHub issue or PR, read it as existing repair context before touching run evidence. +4. Capture the state of the linked artifact: + - issue open or closed + - PR open, merged, closed, or superseded + - latest comments, review comments, and review decisions +5. Only after that, review the `runs` array and pick one representative run. +6. Read: + - `result` + - `trace` + - preferably `evaluation-trace` +7. Summarize the concrete failure signal. +8. Only then decide whether the issue is non-actionable or should proceed into repo repair. +9. Patch the issue with the current evidence. +10. If the issue is actionable in `mcp/src` or `config/source/skills`, continue into the worktree and PR workflow instead of stopping here. +11. If the issue already has a linked PR, use its current status plus later review or evaluation evidence to decide whether the same line of work should continue or whether a new iteration is needed. + +## Existing-artifact preflight + +Before starting a new iteration, always check: + +1. current attribution `notes` +2. `externalUrl` +3. linked GitHub issue or PR state +4. latest comments and review decisions on the linked GitHub artifact + +Do not skip this preflight just because the attribution already has a linked PR. The purpose is to decide whether the next action is: + +- continue the same PR +- update the linked issue first +- start a new worktree and branch because the previous direction is stale or wrong + +## Closure preflight + +Do this again immediately before moving an attribution to `resolved`, even if you already completed the normal preflight earlier in the same session. + +Check: + +1. the latest linked GitHub issue or PR state +2. top-level PR comments +3. review comments +4. review decisions +5. issue comments when `externalUrl` points to an issue +6. whether any of the above arrived after the latest code push, PR update, or fresh evaluation result + +If new unresolved feedback exists, do not mark the attribution `resolved`. Move it back to or keep it at `in_progress` and continue the repair loop. + +## Working set rules + +Build the default working set from two buckets: + +1. issues returned by the focused `category=tool` query +2. issues returned by the focused `category=skill` query + +Deduplicate by `issueId` before processing. + +Only in fallback mode, add a third candidate bucket: + +3. issues returned by the broader todo query that clearly map to: + - `config/source/skills` + - skill activation + - skill content + - skill routing + - skill knowledge gaps + +Fallback-mode candidates do not become real repair work automatically. They must first satisfy stronger evidence checks from `result`, `trace`, and `evaluation-trace`. + +## Run selection policy + +Prefer the run that is most useful for diagnosis: + +1. latest failed run +2. lowest score run +3. highest-signal run with the clearest tool or evaluation failure + +If there are multiple similar runs, read the most recent one first and only read more runs if the first run is ambiguous. + +## What to inspect in each run + +### Result + +Check: + +- overall status +- overall score +- failed tests or checks +- timeout or environment-level failures + +### Trace + +Check: + +- actual conversation decisions +- which tools were called +- whether the tool choice matched the task +- tool call failures, retries, malformed arguments, or missing follow-up steps + +### Evaluation trace + +Use this to identify: + +- the exact failed check name +- whether the failure is about missing evidence, incorrect value, or missing action +- whether the run failed because of MCP output, grader expectations, or external environment + +## Patch policy + +When patching an attribution: + +- always set `owner` to `codex` +- keep `notes` concise and auditable +- only set `externalUrl` when you have a real GitHub issue or PR link +- do not modify unrelated fields + +Treat PATCH as a checkpoint, not the entire job. For a real MCP defect, you will usually patch at least twice: + +1. once after diagnosis, usually as `in_progress` +2. again after GitHub issue or PR linkage, usually with a stronger closure state + +If real evaluation is available, you may patch a third time after the fresh evaluation result is known. + +## Status rules + +### `todo` + +Keep `todo` when: + +- no one has really investigated the issue yet +- the run evidence is incomplete or contradictory +- you cannot tell whether the issue is actionable in `mcp/src` + +### `in_progress` + +Use `in_progress` when: + +- the issue is real and you are actively following it up +- a repo fix or external issue is needed but closure is not complete yet +- you have a strong direction but still need more validation + +This is the default state for actionable issues before the PR or final closure link exists. + +It is also the default state when a PR exists but review feedback or fresh evaluation still requires another iteration. + +### `resolved` + +Use `resolved` only when there is clear closure evidence, for example: + +- an existing GitHub issue or PR already tracks the exact problem +- the fix is already implemented and verified +- the issue is clearly a duplicate of an already tracked and linked problem + +Never mark `resolved` from intuition alone. + +Do not mark `resolved` just because you understand the bug. Mark it only after you have explicit closure evidence. + +Do not mark `resolved` from a stale artifact read. If a linked PR or issue exists, you must complete the closure preflight immediately before patching `resolved`. + +If a post-PR evaluation interface is available, prefer using that fresh evaluation result as part of the closure evidence. + +### `invalid` + +Use `invalid` when evidence shows: + +- the attribution is a false positive +- the failure is purely environment-related +- the grader expectation is wrong while MCP behavior is already correct +- the issue does not require repo action + +## Notes template + +Use a compact evidence record like this: + +```text +run=/; result=; score=; failed_check=; tool_signal=; code_signal=; conclusion= +``` + +Add one more clause when needed: + +```text +next= +``` + +## External URL policy + +Set `externalUrl` only when you have an exact link to: + +- a matching GitHub issue +- a matching PR + +Do not put search results or speculative links into `externalUrl`. + +## Red flags + +Stop and keep the issue unclosed if any of these are true: + +- you have not read at least one `result` and `trace` +- the only signal is the attribution title with no run evidence +- the failure is mixed across multiple unrelated problems +- you cannot tell whether the problem lives in MCP code, the environment, or the grader + +Also stop short of `resolved` if you have not yet completed the GitHub issue / worktree / PR loop for an actionable repo bug. + +Also stop short of `resolved` if there are newer PR comments, review comments, review decisions, or issue comments that have not been re-read after the latest push or evaluation. diff --git a/.agents/skills/mcp-attribution-worktree/references/subagent-orchestration.md b/.agents/skills/mcp-attribution-worktree/references/subagent-orchestration.md new file mode 100644 index 00000000..3e164ab1 --- /dev/null +++ b/.agents/skills/mcp-attribution-worktree/references/subagent-orchestration.md @@ -0,0 +1,108 @@ +# Sub-agent Orchestration + +## Purpose + +Use this reference when you are dispatching one or more sub-agents to process MCP attribution issues. + +The goal is to keep each worker issue-scoped, audit-friendly, and resistant to premature closure. + +## Core rule + +One sub-agent owns exactly one attribution issue. + +Do not give one worker multiple issues. +Do not mix worktrees, evidence, or PR context across issues. + +## Dispatcher responsibilities + +The parent agent or dispatcher must: + +1. fetch the backlog +2. deduplicate issues +3. assign one issue per worker +4. include the exact `issueId` and title in the worker prompt +5. require the worker to read the skill plus the relevant references first +6. require the worker to report back: + - attribution conclusion + - current attribution status + - worktree and branch + - GitHub issue or PR URL + - latest evaluation case and run when relevant + - touched files + - remaining blockers + +The dispatcher must not assume a worker is done just because it returned a PR URL. + +## Worker contract + +Every worker prompt should explicitly require this sequence: + +1. read attribution detail +2. read current `notes` +3. read `externalUrl` when present +4. read linked GitHub issue or PR state +5. read top-level PR comments, review comments, and review decisions when a PR exists +6. only then read representative run `result` and `trace` +7. decide actionable vs invalid +8. if actionable, use `wt` to create an isolated worktree +9. implement the fix and run the smallest relevant validation +10. create or update the GitHub issue or PR +11. run a real evaluation when available +12. perform a closure sweep before changing anything to `resolved` +13. patch attribution only through the report API + +## Required worker prompt clauses + +Include clauses like these in every worker prompt: + +- "You are responsible for exactly one issue." +- "Do not process any other issue." +- "Do not use the shared checkout for code edits." +- "Use Worktrunk for any repairable issue." +- "Read PR comments, review comments, and review decisions before deciding next steps." +- "Before marking the attribution `resolved`, re-read the latest PR comments, review comments, review decisions, and issue comments after the latest push or evaluation result." +- "If unresolved newer feedback exists, keep the attribution `in_progress`." +- "Update attribution only through `http://127.0.0.1:5174/api/...`." +- "`owner` must be `codex`." + +## Recommended worker output format + +Ask workers to return: + +```text +issue conclusion: +attribution status: +worktree / branch: +GitHub issue / PR: +evaluation caseId / runId / result: +modified files: +remaining blockers: +``` + +This makes it easy for the dispatcher to apply closure-sweep checks consistently. + +## Closure-sweep rule for dispatchers + +Even if a worker says the issue is closed: + +1. reopen the linked PR or issue yourself +2. check whether there are newer comments or review signals +3. only then accept a `resolved` recommendation + +If the dispatcher finds newer unresolved feedback, override the worker's closure and move the issue back to `in_progress`. + +## Failure modes to guard against + +- worker reads run evidence but skips PR comments +- worker closes after a passing evaluation without re-reading the PR +- worker treats a PR URL as sufficient closure +- worker continues an old PR without checking whether review changed the direction +- worker edits code in the shared checkout instead of a worktree +- worker handles multiple issues in one prompt and contaminates context + +## Minimal dispatcher checklist + +- Did each worker get exactly one `issueId`? +- Did each worker prompt require preflight before run diagnosis? +- Did each worker prompt require closure sweep before `resolved`? +- Did I independently verify any worker-proposed `resolved` state against the latest PR or issue feedback? diff --git a/.agents/skills/mcp-attribution-worktree/references/value-triage.md b/.agents/skills/mcp-attribution-worktree/references/value-triage.md new file mode 100644 index 00000000..24fd7ab6 --- /dev/null +++ b/.agents/skills/mcp-attribution-worktree/references/value-triage.md @@ -0,0 +1,141 @@ +# Value Triage + +## Purpose + +Use this reference to decide whether a `tool` attribution issue or a skills-related attribution issue is actually valuable, whether it belongs in `mcp/src` or `config/source/skills`, how to map the failure to the right code surface, and whether the agent should continue into a repo repair loop. + +## High-value issue criteria + +Treat an issue as high-value when most of these are true: + +- it affects a core MCP capability +- it reproduces across more than one run, or has a very low score on a critical path +- the failing signal points to missing capability, bad defaults, incomplete return data, or weak operator guidance +- you can map the failure to one or more specific modules in `mcp/src` +- fixing it would improve future agent behavior, not just one isolated run + +## Lower-value or non-actionable cases + +Be cautious when the issue looks like one of these: + +- browser or runtime dependencies missing in the evaluation environment +- temporary CloudBase platform instability +- grader schema mismatch while the MCP output already contains the correct substance +- duplicate attribution already tracked elsewhere +- a flow that fundamentally requires human interaction in a non-interactive evaluation environment + +These often end up as `invalid` or remain `todo` until stronger evidence appears. + +## Decision ladder + +For each issue, decide in this order: + +1. Is the failing signal real? +2. Is it caused by MCP code or design? +3. If yes, is there a specific module or tool boundary to change? +4. If no, is it an environment issue, grader issue, or duplicate? +5. Is the issue strong enough to justify a GitHub issue, repo fix, and PR? +6. If a PR already exists, does the next iteration belong on that line of work or does the direction need to change? + +When the category is not explicitly `tool`, still include the issue if the title, detail, trace, or evaluation evidence shows that the failure belongs to skill activation, skill content, skill routing, or missing knowledge under `config/source/skills`. + +## Common categories + +### Real MCP defect + +Typical signs: + +- missing fields that the underlying tool should reasonably return +- parameters are hard to use, misleading, or silently wrong +- tool output shape prevents downstream extraction +- important next-step guidance is absent in a known failure mode + +Typical outcome: + +- `in_progress` if work is still ongoing +- `resolved` if there is already an external issue, PR, or landed fix + +Default agent action: + +- continue into worktree repair unless blocked + +### Grader or output-contract mismatch + +Typical signs: + +- the trace and result contain the required substance +- the checker expects a different field name or nesting pattern +- the MCP behavior is reasonable, but the evaluator wants another schema + +Typical outcome: + +- often `invalid` +- sometimes `in_progress` if you decide to improve MCP output shape anyway + +Default agent action: + +- do not open a repair worktree unless you intentionally decide to change MCP output compatibility + +### Environment or platform issue + +Typical signs: + +- missing browsers or system packages +- transient provisioning failures outside MCP control +- human-login flows used in headless automation + +Typical outcome: + +- usually `invalid` +- or `todo` if you still need stronger evidence + +Default agent action: + +- explain why this should not turn into a repo fix + +## `mcp/src` mapping table + +Use this map to move from attribution title to code inspection quickly. + +| Failure pattern | Primary code to inspect | Typical questions | +| --- | --- | --- | +| Env info, hosting info, package info missing | `mcp/src/tools/env.ts`, `mcp/src/tools/hosting.ts` | Is the field missing upstream, filtered out, or never requested? | +| NoSQL collection, document, schema, readiness | `mcp/src/tools/databaseNoSQL.ts`, `mcp/src/tools/dataModel.ts` | Is the capability missing, or is the return shape too nested or ambiguous? | +| SQL / MySQL lifecycle or query management | `mcp/src/tools/databaseSQL.ts`, `mcp/src/tools/env.ts` | Is there a lifecycle gap, weak provisioning guidance, or undiscoverable path? | +| Cloud function creation, deployment, HTTP mode | `mcp/src/tools/functions.ts`, `mcp/src/tools/gateway.ts` | Are defaults misleading, schemas unclear, or follow-up steps omitted? | +| Environment creation, destruction, renewal | `mcp/src/tools/env.ts`, `mcp/src/tools/capi.ts`, `mcp/src/tools/setup.ts` | Is there a missing dedicated tool, or only a raw API escape hatch with poor guidance? | +| Auth loops or device-code friction | `mcp/src/tools/interactive.ts`, `mcp/src/tools/env.ts` | Is this a tool defect, or an automation-incompatible flow behaving as designed? | +| Download and IDE setup behavior | `mcp/src/tools/setup.ts`, `mcp/src/tools/download.ts` | Is the file mapping incomplete, or is the issue outside MCP itself? | +| Skill activation, skill content, skill routing, missing knowledge | `config/source/skills/*`, optionally `config/source/guideline/*` | Is the failure caused by missing knowledge, weak trigger wording, bad routing, or inconsistent contracts? | + +## Code review checklist for attribution triage + +Before concluding a tool issue is actionable, verify: + +- the tool is actually registered +- the relevant schema or handler exposes the needed capability +- the returned content matches what the agent would realistically need +- the trace failure is not caused by wrong tool choice by the model +- the problem is not already fixed on the current branch +- for skills-related issues, the true source of truth is under `config/source/skills/`, not the root `skills/` maintenance directory + +## Conclusion patterns + +Use one of these conclusion shapes in `notes`: + +- `real_mcp_gap`: the tool or output is genuinely incomplete +- `guidance_gap`: the tool exists, but the usage contract is too weak +- `grader_mismatch`: MCP output is adequate, evaluator expects another shape +- `environment_noise`: the run failed outside MCP control +- `duplicate_external`: already tracked elsewhere + +## Escalation rule + +Open or link a GitHub issue only when the problem is both: + +- real enough to justify maintenance work +- specific enough that another maintainer could act on your notes without redoing the entire investigation + +When those two conditions are met and the problem lives in `mcp/src`, do not stop at issue linkage. Continue into isolated repair and PR creation unless the environment is explicitly blocked. + +Apply the same rule when the problem lives in `config/source/skills/`: continue into isolated repair and PR creation unless blocked. diff --git a/.agents/skills/mcp-attribution-worktree/references/worktree-repair.md b/.agents/skills/mcp-attribution-worktree/references/worktree-repair.md new file mode 100644 index 00000000..c7b8360f --- /dev/null +++ b/.agents/skills/mcp-attribution-worktree/references/worktree-repair.md @@ -0,0 +1,178 @@ +# Worktree Repair + +## Purpose + +Use this reference when an attribution issue is real, actionable, and worth taking into a repo fix. This is the default next step for repairable MCP issues or repairable CloudBase skill-source issues, not an optional extra. + +## Worktrunk requirement + +This skill is designed around Worktrunk. + +Prefer: + +- `wt switch` +- `wt list` +- `wt remove` + +Do not silently fall back to a shared checkout once you decide to repair an issue. If `wt` is unavailable, stop and report that Worktrunk is missing. + +This keeps issue repair isolated and prevents cross-issue contamination. + +## One issue, one worktree + +Each actionable attribution issue gets: + +- one dedicated branch +- one dedicated worktree +- one dedicated GitHub issue or PR trail when needed + +Never repair two attribution issues in the same worktree. + +## Suggested naming + +Use a branch name that stays close to the issue: + +```text +feature/attribution- +``` + +Examples: + +- `feature/attribution-envquery-hosting-fields` +- `feature/attribution-nosql-output-shape` + +## Basic workflow + +1. Confirm the issue is actionable from run evidence. +2. Check whether a matching GitHub issue or PR already exists. +3. If a GitHub issue or PR already exists, read its state first: + - issue open or closed + - PR open, merged, closed, or superseded +4. If a PR already exists, read its comments and review state before deciding whether to continue on that line or open a new iteration. +5. If needed, create a GitHub issue with a concise title and evidence summary. +6. Create a dedicated Worktrunk worktree. +7. Implement the fix inside that worktree only. +8. Run the smallest relevant validation for the touched code. +9. Commit and open or update a PR when the fix is ready. +10. If a real evaluation interface exists, run a fresh evaluation after the code change or PR update. +11. Patch the attribution with `owner=codex`, updated `notes`, `resolutionStatus`, and `externalUrl` when relevant. + +Do not stop after step 4 for a repairable issue unless the environment prevents code work, PR creation, or real evaluation. + +## Worktrunk commands + +Create a worktree: + +```bash +wt switch --create feature/attribution- +``` + +Inspect active worktrees: + +```bash +wt list +``` + +Clean up after merge: + +```bash +wt remove +``` + +## GitHub issue workflow + +Before creating a new GitHub issue: + +- search for the same tool, module, or symptom +- prefer linking an existing issue instead of opening a duplicate + +When creating a new issue, include: + +- the attribution title +- the representative run +- the failing check or score signal +- the relevant MCP module +- the likely fix direction + +Then copy the final GitHub issue URL into `externalUrl`. + +## PR workflow + +If you implement a fix: + +- keep the change scoped to the single attribution issue +- mention the attribution issue ID and representative run in the PR body or commit context +- add the PR URL to `externalUrl` if that URL is the most direct closure link +- prefer opening the PR in the same session once validation passes + +If the PR already exists: + +- read its state, comments, and review state before changing direction +- prefer continuing the existing PR when the fix direction is still fundamentally correct +- start a new iteration only when review or new evidence shows the approach itself was wrong + +Before changing the attribution to `resolved`, read the PR state, top-level comments, review comments, and review decisions again after the latest push or evaluation result. Do not close from a stale read. + +Do not mark the attribution `resolved` until the closure link is real and the repair path is clear. + +If real evaluation is available, do not treat PR creation alone as closure. Use the fresh evaluation result to decide whether another repair loop is needed. + +## Status guidance during repair + +### Before code work starts + +Use `in_progress` if: + +- the issue is confirmed +- you know which code path to change +- the worktree or GitHub issue is being prepared + +### During code work + +Keep `in_progress` while: + +- the fix is being implemented +- validation is incomplete +- the PR is not open yet + +### After closure + +Use `resolved` when: + +- there is an exact GitHub issue or PR link in `externalUrl` +- or the fix is already landed and the closure is explicit in `notes` +- and there is no newer unresolved PR comment, review comment, or review decision waiting on follow-up + +## Evidence template for GitHub issue creation + +Use a short structure like this: + +```markdown +## Signal + +- Attribution: +- Run: / +- Score / failure: + +## Why this is actionable + +- Relevant module: +- Current behavior: +- Expected behavior: + +## Proposed direction + +- +``` + +## Final check + +Before closing the attribution loop, verify: + +- the worktree contains only this issue's changes +- the branch name is issue-specific +- `externalUrl` points to a real GitHub issue or PR +- `notes` explain why the current status is justified +- the agent did not stop at attribution state changes when repo repair was possible +- if a PR or issue already existed, the agent incorporated that context into the new iteration +- if the attribution was marked `resolved`, the agent re-read the latest PR comments and review state immediately before closing it diff --git a/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/README.md b/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/README.md new file mode 100644 index 00000000..5dce3ccf --- /dev/null +++ b/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/README.md @@ -0,0 +1,29 @@ +# Attribution issue context + +- issueId: issue_mnzgm6vs_zs4kzk +- category: skill +- canonicalTitle: Skill 未引导 Agent 使用正确的部署工具路径，导致 HTTP 云函数创建后实际未生效 +- resolutionStatus: todo +- owner: (none) +- representativeRun: atomic-js-cloudbase-http-function-basic/2026-04-15T02-49-54-801ec1 +- worktree: /Users/bookerzhao/Projects/CloudBase-AI-Coding-Evaluation-Set/.codebuddy/attribution-worktrees-realrun/worktrees/issue-mnzgm6vs-zs4kzk +- branch: automation/attribution-issue-mnzgm6vs-zs4kzk-skill-agent-http +- repo: TencentCloudBase/CloudBase-MCP +- docsSyncEnabled: no + +Inspect these files as needed: +- `.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/issue.json` +- `.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/representative-evidence.json` +- `.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/run-result.json` +- `.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/run-trace.json` +- `.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/evaluation-trace.json` + +Recommended shell commands: +- `pwd` +- `ls -la` +- `cat ` +- `sed -n "1,160p" ` +- `rg ` +- `git status --short` + +Do not run `git commit`, `git push`, or `gh pr create`. diff --git a/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/evaluation-trace.json b/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/evaluation-trace.json new file mode 100644 index 00000000..870cc2bd --- /dev/null +++ b/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/evaluation-trace.json @@ -0,0 +1 @@ +(none) diff --git a/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/issue.json b/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/issue.json new file mode 100644 index 00000000..36d03327 --- /dev/null +++ b/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/issue.json @@ -0,0 +1,23 @@ +{ + "issueId": "issue_mnzgm6vs_zs4kzk", + "category": "skill", + "canonicalTitle": "Skill 未引导 Agent 使用正确的部署工具路径，导致 HTTP 云函数创建后实际未生效", + "resolutionStatus": "todo", + "runCount": 1, + "lastSeenAt": "2026-04-15T02:57:23.775Z", + "createdAt": "2026-04-15T02:57:09.209Z", + "updatedAt": "2026-04-15T04:21:18.750Z", + "runs": [ + { + "caseId": "atomic-js-cloudbase-http-function-basic", + "runId": "2026-04-15T02-49-54-801ec1", + "category": "skill", + "title": "Skill 未引导 Agent 使用正确的部署工具路径，导致 HTTP 云函数创建后实际未生效", + "status": "done", + "runStatus": "fail", + "runTs": "2026-04-15T02:49:54.992Z", + "runScoreOverall": 0.428, + "updatedAt": "2026-04-15T02:57:23.775Z" + } + ] +} diff --git a/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/representative-evidence.json b/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/representative-evidence.json new file mode 100644 index 00000000..870cc2bd --- /dev/null +++ b/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/representative-evidence.json @@ -0,0 +1 @@ +(none) diff --git a/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/run-result.json b/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/run-result.json new file mode 100644 index 00000000..fb820018 --- /dev/null +++ b/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/run-result.json @@ -0,0 +1,173 @@ +{ + "caseId": "atomic-js-cloudbase-http-function-basic", + "runId": "2026-04-15T02-49-54-801ec1", + "ts": "2026-04-15T02:49:54.992Z", + "agent": { + "type": "codebuddy-code", + "model": "glm-5.0-ioa", + "rulesRef": "unknown" + }, + "agentSdkVersion": "0.3.117", + "mcpVersion": null, + "mcpEnabled": false, + "tcbCliEnabled": false, + "tcbCliVersion": null, + "skillSourceRef": "file:///tmp/cloudbase-allinone-eval/cloudbase", + "projectStructure": { + "root": ".", + "tree": [ + { + "name": ".codebuddy", + "type": "dir", + "children": [ + { + "name": "skills", + "type": "dir", + "children": [ + { + "name": "cloudbase", + "type": "dir", + "children": [ + { + "name": "references", + "type": "dir", + "children": [ + { + "name": "ai-model-nodejs", + "type": "dir", + "children": [ + { + "name": "SKILL.md", + "size": 8174, + "type": "file" + } + ] + }, + { + "name": "ai-model-web", + "type": "dir", + "children": [ + { + "name": "SKILL.md", + "size": 6021, + "type": "file" + } + ] + }, + { + "name": "ai-model-wechat", + "type": "dir", + "children": [ + { + "name": "SKILL.md", + "size": 6968, + "type": "file" + } + ] + }, + { + "name": "auth-nodejs", + "type": "dir", + "children": [ + { + "name": "SKILL.md", + "size": 17480, + "type": "file" + } + ] + }, + { + "name": "auth-tool", + "type": "dir", + "children": [ + { + "name": "checklist.md", + "size": 1297, + "type": "file" + }, + { + "name": "SKILL.md", + "size": 16416, + "type": "file" + } + ] + }, + { + "name": "auth-web", + "type": "dir", + "children": [ + { + "name": "SKILL.md", + "size": 14072, + "type": "file" + } + ] + }, + { + "name": "auth-wechat", + "type": "dir", + "children": [ + { + "name": "SKILL.md", + "size": 14360, + "type": "file" + } + ] + }, + { + "name": "cloud-functions", + "type": "dir", + "children": [ + { + "name": "references", + "type": "dir", + "children": [ + { + "name": "event-functions.md", + "size": 3411, + "type": "file" + }, + { + "name": "http-functions.md", + "size": 4451, + "type": "file" + }, + { + "name": "operations-and-config.md", + "size": 4468, + "type": "file" + } + ] + }, + { + "name": "checklist.md", + "size": 1155, + "type": "file" + }, + { + "name": "references.md", + "size": 1358, + "type": "file" + }, + { + "name": "SKILL.md", + "size": 8776, + "type": "file" + } + ] + }, + { + "name": "cloud-storage-web", + "type": "dir", + "children": [ + { + "name": "SKILL.md", + "size": 8732, + "type": "file" + } + ] + }, + { + "name": "cloudbase-agent", + "type": "di +...[truncated] diff --git a/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/run-trace.json b/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/run-trace.json new file mode 100644 index 00000000..930eca8b --- /dev/null +++ b/.codebuddy/attribution-context/issue_mnzgm6vs_zs4kzk/run-trace.json @@ -0,0 +1,25 @@ +{ + "conversation": [ + { + "turn": 1, + "role": "user", + "content": "[Runtime capability notice]\nCurrent run mode tag: allinone\nEnabled capabilities:\n- CloudBase all-in-one skill\nDisabled capabilities:\n- CloudBase CLI\n- CloudBase MCP tools\n- CloudBase scattered skills\n- CloudBase API skill\n- CloudBase Copilot API skill\nUse only the enabled capabilities that are directly available in this run.\nIf the task does not explicitly require a specific interface, prefer the enabled capabilities above and do not assume disabled CLI, MCP, or Skills are available.\n\n[Task]\n我想创建一个可以通过 HTTP 直接访问的云函数，不用 SDK 调用。\n在当前 CloudBase 项目里帮我创建一个叫 apiDemo 的 HTTP 云函数：\n\n功能要求：\n1. 这是一个 HTTP 类型的云函数\n\n2. 支持 GET 请求：访问时从 query 参数获取 name，返回 JSON：{ message: \"Hello, !\", method: \"GET\" }\n 如果没有 name 参数，就返回 { message: \"Hello, Guest!\", method: \"GET\" }\n\n3. 支持 POST 请求：从 body 中解析 JSON，获取 name 和 age，返回：\n { message: \"Received data\", data: { name: \"\", age: }, method: \"POST\" }\n\n4. 返回的 HTTP 状态码都是 200\n\n5. 配置 HTTP 访问服务：\n - 使用默认域名\n - 触发路径设置为 /api/demo\n\n写好云函数代码并部署，然后配置好 HTTP 访问服务，让我可以通过 HTTP 请求直接访问这个函数。\n部署完成后，请调用 `writeSecurityRule(resourceType=\"function\", aclTag=\"CUSTOM\", rule=\"true\")` 配置函数安全规则，允许匿名用户访问；HTTP 云函数默认安全规则不允许匿名访问，不配置会导致外部 HTTP 调用返回 `EXCEED_AUTHORITY`。\n", + "timestamp": "2026-04-15T02:49:57.542Z" + }, + { + "turn": 1, + "role": "assistant", + "content": "[Tool: Skill]", + "timestamp": "2026-04-15T02:50:04.225Z", + "toolCalls": [ + { + "tool": "Skill", + "args": { + "args": "创建 HTTP 云函数", + "skill": "cloud-functions" + }, + "result": [ + { + "type": "text", + "text": "cloud-functions cloud-functions 创建 HTTP 云函数\nBase directory for this skill: /private/var/folders/5f/k5rgxjhn4_s47bx9hdj1m9z4kj5hh3/T/tcb-eval-eb4383f4d902/atomic-js-cloudbase-http-function-basic/2026-04-15T02-49-54-801ec1/.codebuddy/skills/cloudbase/references/cloud-functions\n## Standalone Install Note\n\nIf this environment only installed the current skill, start from the CloudBase main entry and use the published `cloudbase/references/...` paths for sibling skills.\n\n- CloudBase main entry: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/SKILL.md`\n- Current skill raw source: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloud-functions/SKILL.md`\n\nKeep local `references/...` paths for files that ship with the current skill directory. When this file points to a sibling skill such as `auth-tool` or `web-development`, use the standalone fallback URL shown next to that reference.\n\n# Cloud Functions Development\n\n## Activation Contract\n\n### Use this first when\n\n- The task is to create, update, deploy, inspect, or debug a CloudBase Event Function or HTTP Function that serves application runtime logic.\n- The request mentions function runtime, function logs, `scf_bootstrap`, function triggers, or function gateway exposure.\n\n### Read before writing code if\n\n- You still need to decide between Event Function and HTTP Function.\n- The task mentions `manageFunctions`, `queryFunctions`, `manageGateway`, or legacy function-tool names.\n- The task might require `callCloudApi` as a fallback for logs or gateway setup.\n\n### Then also read\n\n- Detailed reference routing -> `./references.md`\n- Auth setup or provider-related backend work -> `../auth-tool/SKILL.md` (standalone fallback: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/auth-tool/SKILL.md`)\n- AI in functions -> `../ai-model-nodejs/SKILL.md` (standalone fallback: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/ai-model-nodejs/SKILL.md`)\n- Long-lived container services or Agent runtimes -> `../cloudrun-development/SKILL.md` (standalone fallback: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/cloudrun-development/SKILL.md`)\n- Calling CloudBase official platform APIs from a client or script -> `../http-api/SKILL.md` (standalone fallback: `https://cnb.cool/tencent/cloud/cloudbase/cloudbase-skills/-/git/raw/main/skills/cloudbase/references/http-api/SKILL.md`)\n\n### Do NOT use for\n\n- CloudRun container services.\n- Web authentication UI implementation.\n- Database-schema design or general data-model work.\n- CloudBase official platform API clients or raw HTTP integrations that only consume platform endpoints.\n\n### Common mistakes / gotchas\n\n- Picking the wrong function type and trying to compensate later.\n- Confusing official CloudBase API client work with building your own HTTP function.\n- Mixing Event Function code shape (`exports.main(event, context)`) with HTTP Function code shape (`req` / `res` on port `9000`).\n- Treating HTTP Access as the implementation model for HTTP Functions. HTTP Access is a gateway configuration for Event Functions, not the HTTP Function runtime model.\n- Forgetting that runtime cannot be changed after creation.\n- Using cloud functions as the first answer for Web login.\n- Forgetting that HTTP Functions must ship `scf_bootstrap`, listen on port `9000`, and include dependencies.\n\n### Minimal checklist\n\n- Read [Cloud Functions Execution Checklist](checklist.md) before deployment or runtime changes.\n- Decide whether the task is Event Function, HTTP Function, or actually CloudRun.\n- Pick the detailed reference file in [references.md](references.md) before writing implementation code.\n\n## Overview\n\nUse this skill when developing, deploying, and operating CloudBase cloud functions. CloudBase has two different programming models:\n\n- **Event Functions**: serverless handlers driven by SDK calls, timers, and o +...[truncated] diff --git a/.codebuddy/skills/mcp-attribution-worktree b/.codebuddy/skills/mcp-attribution-worktree deleted file mode 120000 index 31107a89..00000000 --- a/.codebuddy/skills/mcp-attribution-worktree +++ /dev/null @@ -1 +0,0 @@ -../../.agents/skills/mcp-attribution-worktree \ No newline at end of file diff --git a/.codebuddy/skills/mcp-attribution-worktree/SKILL.md b/.codebuddy/skills/mcp-attribution-worktree/SKILL.md new file mode 100644 index 00000000..41839b8e --- /dev/null +++ b/.codebuddy/skills/mcp-attribution-worktree/SKILL.md @@ -0,0 +1,139 @@ +--- +name: mcp-attribution-worktree +description: Triage, repair, and close MCP attribution issues from the local report API with evidence-driven decisions and isolated Worktrunk worktrees. Use this skill when Codex needs to process `tool` attribution issues and skills-related attribution issues, inspect related runs, decide whether the issue is actionable in `mcp/src` or `config/source/skills`, update attribution fields as `owner=codex`, and then complete the fix loop through GitHub issue tracking, worktree-based code changes, PR submission, and follow-up iteration when the problem is repairable. +--- + +# MCP Attribution Worktree + +Process MCP and skills-related attribution issues as an auditable maintenance workflow instead of ad-hoc debugging. + +## What this skill does + +Use this skill to: + +- fetch pending MCP and skills-related attribution issues from the local report API +- inspect issue detail plus representative runs before making any status decision +- map failures back to concrete `mcp/src` tools, `config/source/skills`, or classify them as environment / grader / duplicate noise +- update attribution issues with concise evidence, `owner=codex`, and links to external GitHub work +- isolate each actionable repair in its own Worktrunk worktree and branch +- carry actionable issues through repo repair and PR creation instead of stopping at issue state updates +- continue from existing GitHub issues or PRs when later review or evaluation feedback shows the first direction was incomplete or wrong +- run a real post-PR evaluation when an evaluation interface is available, and use that result to decide whether another repair loop is needed + +## Do not use this skill for + +- generic bug fixing without attribution evidence +- unrelated attribution categories that do not map to `mcp/src` or `config/source/skills` +- bulk repo changes unrelated to a specific attribution issue +- direct database or backend mutation outside the documented report API endpoints + +## Workflow + +1. Start with focused `tool` and `skill` backlog queries. +2. Process one issue at a time. Never mix evidence, notes, or worktrees across issues. +3. Run the existing-artifact preflight before choosing the representative run: read issue detail, current notes, existing `externalUrl`, and the state of any linked GitHub issue or PR. If a GitHub issue or PR already exists, treat it as part of the current state, not a finished endpoint. +4. Read at least one run's `result` and `trace`. Prefer to also read `evaluation-trace`. +5. Check the relevant implementation in `mcp/src` or `config/source/skills` before deciding whether the issue is actionable. +6. If the issue is actionable in repo code or skills content, do not stop at attribution triage. Open or link the matching GitHub issue, create a dedicated Worktrunk worktree, implement the fix, validate it, and prepare a PR. +7. If review comments, review decisions, or later evidence show the direction is wrong, start another focused iteration from the existing GitHub issue or PR context and continue improving instead of treating the first PR as final. +8. Update attribution fields through the report API after you have the right evidence, and update them again when the GitHub issue, PR, or evaluation result becomes available. +9. Before changing an attribution to `resolved`, run a closure preflight on the linked GitHub artifact again: reread the latest PR comments, review comments, review decisions, and issue comments after the most recent code push or evaluation result. +10. When a real evaluation interface exists, run a post-PR evaluation and use the result plus the closure preflight to decide whether to continue iterating or mark the issue closed. +11. Only stop after the issue is either clearly non-actionable or has been carried through the repair loop as far as the current environment allows. + +## Common requests + +- "Automatically process the pending MCP attribution issues." +- "Look at the tool and skills attribution backlog, fix the real issues, and update attribution with evidence." +- "Find valuable MCP attribution problems and fix them in isolated worktrees." +- "For each tool issue, decide whether it is a real `mcp/src` bug or just evaluation noise." +- "Continue iterating on the existing issue or PR after review comments." +- "After opening the PR, run a real evaluation and fix the next round if it still fails." + +## Routing + +| Task | Read | +| --- | --- | +| Run the report API triage flow and update attribution fields across tool and skills-related issues | `references/report-api-workflow.md` | +| Decide whether an issue is valuable and map it to `mcp/src` or `config/source/skills` | `references/value-triage.md` | +| Create GitHub issues, use Worktrunk, and repair the repo in isolation | `references/worktree-repair.md` | +| Continue from review feedback or real evaluation results after a PR already exists | `references/iteration-loop.md` | +| Trigger real evaluation runs and interpret the result | `references/evaluation-verification.md` | +| Dispatch one issue per worker and enforce closure-sweep rules in sub-agent prompts | `references/subagent-orchestration.md` | + +## Operating rules + +- Only update attribution issues through the local report API. +- Treat `owner` as fixed: always set it to `codex` when you patch an attribution. +- Before any new iteration, always inspect the latest attribution `notes`, `externalUrl`, linked GitHub issue or PR status, and any available PR comments or review decisions. +- Before moving any issue to `resolved`, always perform a fresh closure sweep on the linked issue or PR after the latest push or evaluation has completed. Do not rely on an earlier preflight. +- Do not change `resolutionStatus` until you have read at least one related run's `result` and `trace`. +- Do not mark an issue `resolved` without clear closure evidence such as an existing GitHub issue, PR, merged fix, or a verified duplicate that already has external tracking. +- Do not mark an issue `resolved` if there are unread or unaddressed PR comments, review comments, review decisions, or issue comments that arrived after the last time you inspected the linked artifact. +- Keep `notes` short but auditable. Include the representative run, the main failing signal, and the code or tool signal that supports the conclusion. +- If the evidence is incomplete, keep the issue `todo` or move it to `in_progress` and explicitly state what is still missing. +- For a real and repairable issue in `mcp/src` or `config/source/skills`, the default expectation is full follow-through: attribution triage, GitHub issue linkage, isolated worktree repair, validation, and PR creation. +- When the fix belongs to CloudBase skill content, edit `config/source/skills/` as the source of truth. Do not treat the root `skills/` directory as the source for those external skills. +- Only stop at status-only attribution updates when the issue is non-actionable, blocked by missing evidence, blocked by missing Worktrunk, or clearly outside MCP repo control. +- Do not use broad uncategorized backlog queries as the default source of work. Only use them in explicit fallback mode when category labels are incomplete or the user asks for a full backlog sweep. +- Items discovered through fallback broad queries must not enter the repair queue until run evidence clearly shows they belong to `mcp/src` or `config/source/skills`. +- Prefer one sub-agent per issue when sub-agent support exists. Give each sub-agent ownership of exactly one issue. If sub-agents are unavailable, process issues serially and keep a strict one-issue-at-a-time context. +- If a repair is needed, use Worktrunk's `wt` workflow for the isolated worktree. If `wt` is unavailable, stop and report that Worktrunk is missing instead of silently falling back to a shared checkout. +- Never reuse the same worktree for multiple attribution issues. +- Do not open or update GitHub issues until you have enough run evidence to explain the problem clearly. +- If an issue already has a GitHub issue or PR, read its current state before starting a new branch or changing direction: open or closed status, latest comments, review decisions, and whether the linked work is already stale or superseded. +- Review comments and post-PR evaluation failures are part of the same repair loop. Use them to drive another iteration instead of prematurely closing the attribution. +- If a real evaluation interface is available, prefer leaving the attribution `in_progress` until the repaired branch or PR passes a fresh evaluation round. +- Do not claim validation success from reasoning alone. Use the evaluation API and the final run result whenever that interface is available. + +## Required preflight + +Before starting a fresh diagnosis or code iteration for an attribution issue, complete this checklist in order: + +1. Read the attribution detail plus the latest `notes`. +2. Read `externalUrl` if present. +3. If `externalUrl` points to a GitHub issue, check whether it is open or closed and whether later comments changed the fix direction. +4. If `externalUrl` points to a PR, check whether it is open, merged, closed, or superseded. +5. Read PR comments, review comments, and review decisions before deciding whether to continue the same branch or start a new iteration. +6. Only after that, pick the representative run and continue into `result`, `trace`, and `evaluation-trace`. + +## Required closure preflight + +Before changing an attribution to `resolved`, complete this checklist in order even if you already did the normal preflight earlier: + +1. Reopen the linked GitHub issue or PR. +2. Re-read the latest top-level comments, review comments, and review decisions. +3. Confirm whether any comment arrived after the latest code push, PR update, or evaluation result. +4. If new feedback exists, keep the attribution `in_progress` and continue the loop. +5. Only if there is no newer unresolved feedback, evaluate whether closure evidence is now strong enough. + +## Quick commands + +```bash +curl -s 'http://127.0.0.1:5174/api/attributions?category=tool&resolutionStatus=todo&limit=50' +curl -s 'http://127.0.0.1:5174/api/attributions?category=skill&resolutionStatus=todo&limit=50' +curl -s "http://127.0.0.1:5174/api/attributions/" +curl -s "http://127.0.0.1:5174/api/runs///result" +curl -s "http://127.0.0.1:5174/api/runs///trace" +curl -s "http://127.0.0.1:5174/api/runs///evaluation-trace" +wt switch --create feature/attribution- +gh issue create --repo TencentCloudBase/CloudBase-MCP +gh pr view --comments --repo TencentCloudBase/CloudBase-MCP +gh pr create --repo TencentCloudBase/CloudBase-MCP +curl -s -X POST http://127.0.0.1:5174/api/evaluations +``` + +## Minimum self-check + +- Did I complete the existing-artifact preflight before starting a new diagnosis or code iteration? +- Did I inspect at least one related run's `result` and `trace` before changing status? +- Did I keep this issue isolated from every other issue? +- Is the issue actually actionable in `mcp/src`, `config/source/skills`, or is it environment / grader noise? +- If the issue was actionable, did I continue into GitHub issue / worktree / PR work instead of stopping at triage? +- If there was already a PR or review thread, did I continue from that feedback instead of ignoring it? +- If a real evaluation interface was available, did I run a fresh evaluation before treating the issue as closed? +- Did I base the validation conclusion on the final evaluation result instead of my own guess? +- If I patched the attribution, did I keep the change limited to `resolutionStatus`, `owner`, `notes`, and `externalUrl` when relevant? +- If I started a fix, does it live in its own Worktrunk worktree and branch? +- If I marked something `resolved`, is there explicit closure evidence? +- If I marked something `resolved`, did I re-read the latest PR comments, review comments, review decisions, and issue comments immediately before closing it? diff --git a/.codebuddy/skills/mcp-attribution-worktree/references/evaluation-verification.md b/.codebuddy/skills/mcp-attribution-worktree/references/evaluation-verification.md new file mode 100644 index 00000000..60ba44a7 --- /dev/null +++ b/.codebuddy/skills/mcp-attribution-worktree/references/evaluation-verification.md @@ -0,0 +1,118 @@ +# Evaluation Verification + +## Purpose + +Use this reference when you need to verify that a proposed fix or repair direction actually works in a real evaluation run. + +## Core rule + +Do not treat implementation or static reasoning as proof of success. + +When the AI Coding Eval Report API is available, validation means: + +1. trigger a real evaluation run +2. wait for it to finish +3. read the final result +4. decide pass or fail from the returned run result + +## Required flow + +After you believe the implementation is ready: + +1. `POST /api/evaluations` +2. record `caseId` and `runId` +3. poll `GET /api/evaluations/{caseId}/{runId}` +4. once finished, read `GET /api/runs/{caseId}/{runId}/result` +5. optionally read `trace` and `evaluation-trace` if the run failed or is ambiguous + +Do not claim "validated" before step 4 is complete. + +## Required request shape + +The request body must include: + +- `caseId` +- `config` + +Typical config fields: + +- `mcp` +- `tcbCli` +- `skillsMode` +- `mcpPackage` +- `skillsRepo` +- `skillsRef` +- `skillsPath` +- `allInOneSkillsRepo` +- `allInOneSkillsRef` +- `allInOneSkillsLocalPath` +- `apiSkillsRepo` +- `apiSkillsRef` +- `apiSkillsPath` +- `agentType` +- `model` +- `evalModel` +- `maxTurns` +- `caseTimeoutSeconds` +- `evaluationTimeoutMs` + +## Local build expectations + +When local MCP code is under test: + +- build `mcp` first +- pass the absolute path to `mcp/dist/cli.cjs` as `config.mcpPackage` + +When `skillsMode=allinone` is under test: + +- build the local all-in-one skill bundle first +- pass the absolute bundle path as `config.allInOneSkillsLocalPath` + +## Result interpretation + +Use the final run result as the source of truth. + +### Pass + +Treat the evaluation as passed when: + +- `result.status == "pass"` +- and there is no failed test signal + +### Fail + +Treat the evaluation as failed when any of these are true: + +- `result.status == "fail"` +- `result.status == "error"` +- `result.status == "timeout"` +- `tests.failed > 0` +- `error` is present + +## Failure follow-up + +If the run fails: + +1. capture the failure summary +2. inspect `trace` and `evaluation-trace` +3. decide whether the problem is: + - still the same root cause + - a new regression + - environment noise +4. continue the repair loop if needed + +## Reporting format + +Every verification summary should include at least: + +- `caseId` +- `runId` +- evaluation status +- overall score when available +- tests passed / failed / total when available +- whether validation passed +- failure reason when it did not pass + +## Attribution rule + +If real evaluation is available, do not move a repairable issue to `resolved` until the final evaluation result supports closure or there is another explicit closure reason. diff --git a/.codebuddy/skills/mcp-attribution-worktree/references/iteration-loop.md b/.codebuddy/skills/mcp-attribution-worktree/references/iteration-loop.md new file mode 100644 index 00000000..d54c90dd --- /dev/null +++ b/.codebuddy/skills/mcp-attribution-worktree/references/iteration-loop.md @@ -0,0 +1,123 @@ +# Iteration Loop + +## Purpose + +Use this reference when an attribution issue already has a linked GitHub issue or PR, or when a new review or evaluation result arrives after the first repair attempt. + +## Core rule + +Treat GitHub issues, PRs, review comments, and fresh evaluation results as part of the same repair loop. + +Do not assume that: + +- the first PR is final +- opening a PR is enough to mark the attribution closed +- an existing `externalUrl` means no more work is needed + +## Existing artifact first + +When an attribution already has `externalUrl` or notes pointing to previous work: + +1. Read that issue or PR first. +2. Capture its current state first: + - issue open or closed + - PR open, merged, closed, or superseded +3. Read comments, review comments, review decisions, and any follow-up discussion. +4. Compare that feedback with the latest attribution run evidence. +5. Decide whether to continue the same approach or redirect it. + +Do not start a new branch, worktree, or diagnosis pass until this check is complete. + +## Closure sweep + +Before you change an attribution from `in_progress` to `resolved`, repeat the artifact check one more time even if you already did it at the start of the iteration. + +You must re-read: + +1. the latest top-level PR comments +2. review comments +3. review decisions +4. linked issue comments when relevant + +Treat any newer unresolved feedback as a new iteration signal. Do not close the attribution off an older snapshot of the PR. + +## Continue vs restart + +### Continue the same PR + +Prefer continuing the same PR when: + +- review feedback asks for corrections, tightening, or missing edge cases +- the overall repair direction is still correct +- the next change is an iteration, not a different root-cause theory + +### Start a new iteration path + +Prefer a new worktree or branch when: + +- review or fresh evaluation shows the first direction was wrong +- the repair target moved from `mcp/src` to `config/source/skills`, or vice versa +- the PR became too mixed or too far from the new diagnosis +- the linked PR is closed, stale, or superseded and continuing it would hide the new root cause + +## Post-PR evaluation + +If a real evaluation interface exists: + +1. run a fresh evaluation after the PR or branch update +2. inspect the resulting run and failed checks +3. decide whether: + - the issue is now closed + - the issue needs another iteration + - the issue turned out to be grader or environment noise + +Use that new evaluation as stronger closure evidence than static reasoning alone. + +## Attribution state during iteration + +### Keep `in_progress` + +Keep the attribution `in_progress` while: + +- a PR exists but review feedback is unresolved +- a fresh evaluation still fails +- the next iteration is already clear + +### Move to `resolved` + +Move to `resolved` only when: + +- the PR or linked issue provides explicit closure +- and any available fresh evaluation no longer shows the original failure mode +- and the closure sweep found no newer unresolved PR comments, review comments, review decisions, or issue comments + +### Move to `invalid` + +Move to `invalid` when later review or evaluation shows: + +- the original attribution was wrong +- the real failure was environment or grader noise +- no repo or skill-source change is actually needed + +## Notes guidance + +When iterating, append evidence like this: + +```text +iteration=; prior=; new_signal=; conclusion= +``` + +This keeps the attribution auditable across multiple rounds. + +## Mandatory iteration checklist + +Before each new iteration: + +1. read attribution `notes` +2. read `externalUrl` +3. inspect linked issue or PR state +4. read comments and review decisions +5. decide continue vs restart +6. only then inspect the next representative run + +Before `resolved`, repeat steps 2-4 after the latest push or evaluation result so the closure decision is based on a fresh artifact read rather than an older preflight snapshot. diff --git a/.codebuddy/skills/mcp-attribution-worktree/references/report-api-workflow.md b/.codebuddy/skills/mcp-attribution-worktree/references/report-api-workflow.md new file mode 100644 index 00000000..aa294720 --- /dev/null +++ b/.codebuddy/skills/mcp-attribution-worktree/references/report-api-workflow.md @@ -0,0 +1,258 @@ +# Report API Workflow + +## Purpose + +Use this reference to process MCP attribution issues through the local report API in a repeatable, auditable order, while treating attribution updates as one part of a larger repair loop rather than the final deliverable. + +## Allowed endpoints + +Use only these attribution endpoints for attribution state: + +- `GET /api/attributions` +- `GET /api/attributions/:issueId` +- `GET /api/runs/:caseId/:runId/result` +- `GET /api/runs/:caseId/:runId/trace` +- `GET /api/runs/:caseId/:runId/evaluation-trace` +- `PATCH /api/attributions/:issueId` + +Do not mutate attribution state through any other backend path. + +## Baseline query + +Start with: + +```text +GET /api/attributions?category=tool&resolutionStatus=todo&limit=50 +``` + +Then query explicit skills backlog too: + +```text +GET /api/attributions?category=skill&resolutionStatus=todo&limit=50 +``` + +Use the first query to get the focused MCP tool backlog. + +Use the second query to get explicitly labeled skills backlog. +Do not run a broad uncategorized backlog query by default. + +## Fallback query + +Only if category labeling looks incomplete, or if the user explicitly asks for a full todo sweep, run: + +```text +GET /api/attributions?resolutionStatus=todo&limit=100 +``` + +Use this broader query only to discover candidates that may have been miscategorized. + +Do not rely on the broad query as the default work source. + +## Per-issue sequence + +For each candidate issue: + +1. Read issue detail with `GET /api/attributions/:issueId`. +2. Review the current `notes` and `externalUrl`. +3. If there is already a linked GitHub issue or PR, read it as existing repair context before touching run evidence. +4. Capture the state of the linked artifact: + - issue open or closed + - PR open, merged, closed, or superseded + - latest comments, review comments, and review decisions +5. Only after that, review the `runs` array and pick one representative run. +6. Read: + - `result` + - `trace` + - preferably `evaluation-trace` +7. Summarize the concrete failure signal. +8. Only then decide whether the issue is non-actionable or should proceed into repo repair. +9. Patch the issue with the current evidence. +10. If the issue is actionable in `mcp/src` or `config/source/skills`, continue into the worktree and PR workflow instead of stopping here. +11. If the issue already has a linked PR, use its current status plus later review or evaluation evidence to decide whether the same line of work should continue or whether a new iteration is needed. + +## Existing-artifact preflight + +Before starting a new iteration, always check: + +1. current attribution `notes` +2. `externalUrl` +3. linked GitHub issue or PR state +4. latest comments and review decisions on the linked GitHub artifact + +Do not skip this preflight just because the attribution already has a linked PR. The purpose is to decide whether the next action is: + +- continue the same PR +- update the linked issue first +- start a new worktree and branch because the previous direction is stale or wrong + +## Closure preflight + +Do this again immediately before moving an attribution to `resolved`, even if you already completed the normal preflight earlier in the same session. + +Check: + +1. the latest linked GitHub issue or PR state +2. top-level PR comments +3. review comments +4. review decisions +5. issue comments when `externalUrl` points to an issue +6. whether any of the above arrived after the latest code push, PR update, or fresh evaluation result + +If new unresolved feedback exists, do not mark the attribution `resolved`. Move it back to or keep it at `in_progress` and continue the repair loop. + +## Working set rules + +Build the default working set from two buckets: + +1. issues returned by the focused `category=tool` query +2. issues returned by the focused `category=skill` query + +Deduplicate by `issueId` before processing. + +Only in fallback mode, add a third candidate bucket: + +3. issues returned by the broader todo query that clearly map to: + - `config/source/skills` + - skill activation + - skill content + - skill routing + - skill knowledge gaps + +Fallback-mode candidates do not become real repair work automatically. They must first satisfy stronger evidence checks from `result`, `trace`, and `evaluation-trace`. + +## Run selection policy + +Prefer the run that is most useful for diagnosis: + +1. latest failed run +2. lowest score run +3. highest-signal run with the clearest tool or evaluation failure + +If there are multiple similar runs, read the most recent one first and only read more runs if the first run is ambiguous. + +## What to inspect in each run + +### Result + +Check: + +- overall status +- overall score +- failed tests or checks +- timeout or environment-level failures + +### Trace + +Check: + +- actual conversation decisions +- which tools were called +- whether the tool choice matched the task +- tool call failures, retries, malformed arguments, or missing follow-up steps + +### Evaluation trace + +Use this to identify: + +- the exact failed check name +- whether the failure is about missing evidence, incorrect value, or missing action +- whether the run failed because of MCP output, grader expectations, or external environment + +## Patch policy + +When patching an attribution: + +- always set `owner` to `codex` +- keep `notes` concise and auditable +- only set `externalUrl` when you have a real GitHub issue or PR link +- do not modify unrelated fields + +Treat PATCH as a checkpoint, not the entire job. For a real MCP defect, you will usually patch at least twice: + +1. once after diagnosis, usually as `in_progress` +2. again after GitHub issue or PR linkage, usually with a stronger closure state + +If real evaluation is available, you may patch a third time after the fresh evaluation result is known. + +## Status rules + +### `todo` + +Keep `todo` when: + +- no one has really investigated the issue yet +- the run evidence is incomplete or contradictory +- you cannot tell whether the issue is actionable in `mcp/src` + +### `in_progress` + +Use `in_progress` when: + +- the issue is real and you are actively following it up +- a repo fix or external issue is needed but closure is not complete yet +- you have a strong direction but still need more validation + +This is the default state for actionable issues before the PR or final closure link exists. + +It is also the default state when a PR exists but review feedback or fresh evaluation still requires another iteration. + +### `resolved` + +Use `resolved` only when there is clear closure evidence, for example: + +- an existing GitHub issue or PR already tracks the exact problem +- the fix is already implemented and verified +- the issue is clearly a duplicate of an already tracked and linked problem + +Never mark `resolved` from intuition alone. + +Do not mark `resolved` just because you understand the bug. Mark it only after you have explicit closure evidence. + +Do not mark `resolved` from a stale artifact read. If a linked PR or issue exists, you must complete the closure preflight immediately before patching `resolved`. + +If a post-PR evaluation interface is available, prefer using that fresh evaluation result as part of the closure evidence. + +### `invalid` + +Use `invalid` when evidence shows: + +- the attribution is a false positive +- the failure is purely environment-related +- the grader expectation is wrong while MCP behavior is already correct +- the issue does not require repo action + +## Notes template + +Use a compact evidence record like this: + +```text +run=/; result=; score=; failed_check=; tool_signal=; code_signal=; conclusion= +``` + +Add one more clause when needed: + +```text +next= +``` + +## External URL policy + +Set `externalUrl` only when you have an exact link to: + +- a matching GitHub issue +- a matching PR + +Do not put search results or speculative links into `externalUrl`. + +## Red flags + +Stop and keep the issue unclosed if any of these are true: + +- you have not read at least one `result` and `trace` +- the only signal is the attribution title with no run evidence +- the failure is mixed across multiple unrelated problems +- you cannot tell whether the problem lives in MCP code, the environment, or the grader + +Also stop short of `resolved` if you have not yet completed the GitHub issue / worktree / PR loop for an actionable repo bug. + +Also stop short of `resolved` if there are newer PR comments, review comments, review decisions, or issue comments that have not been re-read after the latest push or evaluation. diff --git a/.codebuddy/skills/mcp-attribution-worktree/references/subagent-orchestration.md b/.codebuddy/skills/mcp-attribution-worktree/references/subagent-orchestration.md new file mode 100644 index 00000000..3e164ab1 --- /dev/null +++ b/.codebuddy/skills/mcp-attribution-worktree/references/subagent-orchestration.md @@ -0,0 +1,108 @@ +# Sub-agent Orchestration + +## Purpose + +Use this reference when you are dispatching one or more sub-agents to process MCP attribution issues. + +The goal is to keep each worker issue-scoped, audit-friendly, and resistant to premature closure. + +## Core rule + +One sub-agent owns exactly one attribution issue. + +Do not give one worker multiple issues. +Do not mix worktrees, evidence, or PR context across issues. + +## Dispatcher responsibilities + +The parent agent or dispatcher must: + +1. fetch the backlog +2. deduplicate issues +3. assign one issue per worker +4. include the exact `issueId` and title in the worker prompt +5. require the worker to read the skill plus the relevant references first +6. require the worker to report back: + - attribution conclusion + - current attribution status + - worktree and branch + - GitHub issue or PR URL + - latest evaluation case and run when relevant + - touched files + - remaining blockers + +The dispatcher must not assume a worker is done just because it returned a PR URL. + +## Worker contract + +Every worker prompt should explicitly require this sequence: + +1. read attribution detail +2. read current `notes` +3. read `externalUrl` when present +4. read linked GitHub issue or PR state +5. read top-level PR comments, review comments, and review decisions when a PR exists +6. only then read representative run `result` and `trace` +7. decide actionable vs invalid +8. if actionable, use `wt` to create an isolated worktree +9. implement the fix and run the smallest relevant validation +10. create or update the GitHub issue or PR +11. run a real evaluation when available +12. perform a closure sweep before changing anything to `resolved` +13. patch attribution only through the report API + +## Required worker prompt clauses + +Include clauses like these in every worker prompt: + +- "You are responsible for exactly one issue." +- "Do not process any other issue." +- "Do not use the shared checkout for code edits." +- "Use Worktrunk for any repairable issue." +- "Read PR comments, review comments, and review decisions before deciding next steps." +- "Before marking the attribution `resolved`, re-read the latest PR comments, review comments, review decisions, and issue comments after the latest push or evaluation result." +- "If unresolved newer feedback exists, keep the attribution `in_progress`." +- "Update attribution only through `http://127.0.0.1:5174/api/...`." +- "`owner` must be `codex`." + +## Recommended worker output format + +Ask workers to return: + +```text +issue conclusion: +attribution status: +worktree / branch: +GitHub issue / PR: +evaluation caseId / runId / result: +modified files: +remaining blockers: +``` + +This makes it easy for the dispatcher to apply closure-sweep checks consistently. + +## Closure-sweep rule for dispatchers + +Even if a worker says the issue is closed: + +1. reopen the linked PR or issue yourself +2. check whether there are newer comments or review signals +3. only then accept a `resolved` recommendation + +If the dispatcher finds newer unresolved feedback, override the worker's closure and move the issue back to `in_progress`. + +## Failure modes to guard against + +- worker reads run evidence but skips PR comments +- worker closes after a passing evaluation without re-reading the PR +- worker treats a PR URL as sufficient closure +- worker continues an old PR without checking whether review changed the direction +- worker edits code in the shared checkout instead of a worktree +- worker handles multiple issues in one prompt and contaminates context + +## Minimal dispatcher checklist + +- Did each worker get exactly one `issueId`? +- Did each worker prompt require preflight before run diagnosis? +- Did each worker prompt require closure sweep before `resolved`? +- Did I independently verify any worker-proposed `resolved` state against the latest PR or issue feedback? diff --git a/.codebuddy/skills/mcp-attribution-worktree/references/value-triage.md b/.codebuddy/skills/mcp-attribution-worktree/references/value-triage.md new file mode 100644 index 00000000..24fd7ab6 --- /dev/null +++ b/.codebuddy/skills/mcp-attribution-worktree/references/value-triage.md @@ -0,0 +1,141 @@ +# Value Triage + +## Purpose + +Use this reference to decide whether a `tool` attribution issue or a skills-related attribution issue is actually valuable, whether it belongs in `mcp/src` or `config/source/skills`, how to map the failure to the right code surface, and whether the agent should continue into a repo repair loop. + +## High-value issue criteria + +Treat an issue as high-value when most of these are true: + +- it affects a core MCP capability +- it reproduces across more than one run, or has a very low score on a critical path +- the failing signal points to missing capability, bad defaults, incomplete return data, or weak operator guidance +- you can map the failure to one or more specific modules in `mcp/src` +- fixing it would improve future agent behavior, not just one isolated run + +## Lower-value or non-actionable cases + +Be cautious when the issue looks like one of these: + +- browser or runtime dependencies missing in the evaluation environment +- temporary CloudBase platform instability +- grader schema mismatch while the MCP output already contains the correct substance +- duplicate attribution already tracked elsewhere +- a flow that fundamentally requires human interaction in a non-interactive evaluation environment + +These often end up as `invalid` or remain `todo` until stronger evidence appears. + +## Decision ladder + +For each issue, decide in this order: + +1. Is the failing signal real? +2. Is it caused by MCP code or design? +3. If yes, is there a specific module or tool boundary to change? +4. If no, is it an environment issue, grader issue, or duplicate? +5. Is the issue strong enough to justify a GitHub issue, repo fix, and PR? +6. If a PR already exists, does the next iteration belong on that line of work or does the direction need to change? + +When the category is not explicitly `tool`, still include the issue if the title, detail, trace, or evaluation evidence shows that the failure belongs to skill activation, skill content, skill routing, or missing knowledge under `config/source/skills`. + +## Common categories + +### Real MCP defect + +Typical signs: + +- missing fields that the underlying tool should reasonably return +- parameters are hard to use, misleading, or silently wrong +- tool output shape prevents downstream extraction +- important next-step guidance is absent in a known failure mode + +Typical outcome: + +- `in_progress` if work is still ongoing +- `resolved` if there is already an external issue, PR, or landed fix + +Default agent action: + +- continue into worktree repair unless blocked + +### Grader or output-contract mismatch + +Typical signs: + +- the trace and result contain the required substance +- the checker expects a different field name or nesting pattern +- the MCP behavior is reasonable, but the evaluator wants another schema + +Typical outcome: + +- often `invalid` +- sometimes `in_progress` if you decide to improve MCP output shape anyway + +Default agent action: + +- do not open a repair worktree unless you intentionally decide to change MCP output compatibility + +### Environment or platform issue + +Typical signs: + +- missing browsers or system packages +- transient provisioning failures outside MCP control +- human-login flows used in headless automation + +Typical outcome: + +- usually `invalid` +- or `todo` if you still need stronger evidence + +Default agent action: + +- explain why this should not turn into a repo fix + +## `mcp/src` mapping table + +Use this map to move from attribution title to code inspection quickly. + +| Failure pattern | Primary code to inspect | Typical questions | +| --- | --- | --- | +| Env info, hosting info, package info missing | `mcp/src/tools/env.ts`, `mcp/src/tools/hosting.ts` | Is the field missing upstream, filtered out, or never requested? | +| NoSQL collection, document, schema, readiness | `mcp/src/tools/databaseNoSQL.ts`, `mcp/src/tools/dataModel.ts` | Is the capability missing, or is the return shape too nested or ambiguous? | +| SQL / MySQL lifecycle or query management | `mcp/src/tools/databaseSQL.ts`, `mcp/src/tools/env.ts` | Is there a lifecycle gap, weak provisioning guidance, or undiscoverable path? | +| Cloud function creation, deployment, HTTP mode | `mcp/src/tools/functions.ts`, `mcp/src/tools/gateway.ts` | Are defaults misleading, schemas unclear, or follow-up steps omitted? | +| Environment creation, destruction, renewal | `mcp/src/tools/env.ts`, `mcp/src/tools/capi.ts`, `mcp/src/tools/setup.ts` | Is there a missing dedicated tool, or only a raw API escape hatch with poor guidance? | +| Auth loops or device-code friction | `mcp/src/tools/interactive.ts`, `mcp/src/tools/env.ts` | Is this a tool defect, or an automation-incompatible flow behaving as designed? | +| Download and IDE setup behavior | `mcp/src/tools/setup.ts`, `mcp/src/tools/download.ts` | Is the file mapping incomplete, or is the issue outside MCP itself? | +| Skill activation, skill content, skill routing, missing knowledge | `config/source/skills/*`, optionally `config/source/guideline/*` | Is the failure caused by missing knowledge, weak trigger wording, bad routing, or inconsistent contracts? | + +## Code review checklist for attribution triage + +Before concluding a tool issue is actionable, verify: + +- the tool is actually registered +- the relevant schema or handler exposes the needed capability +- the returned content matches what the agent would realistically need +- the trace failure is not caused by wrong tool choice by the model +- the problem is not already fixed on the current branch +- for skills-related issues, the true source of truth is under `config/source/skills/`, not the root `skills/` maintenance directory + +## Conclusion patterns + +Use one of these conclusion shapes in `notes`: + +- `real_mcp_gap`: the tool or output is genuinely incomplete +- `guidance_gap`: the tool exists, but the usage contract is too weak +- `grader_mismatch`: MCP output is adequate, evaluator expects another shape +- `environment_noise`: the run failed outside MCP control +- `duplicate_external`: already tracked elsewhere + +## Escalation rule + +Open or link a GitHub issue only when the problem is both: + +- real enough to justify maintenance work +- specific enough that another maintainer could act on your notes without redoing the entire investigation + +When those two conditions are met and the problem lives in `mcp/src`, do not stop at issue linkage. Continue into isolated repair and PR creation unless the environment is explicitly blocked. + +Apply the same rule when the problem lives in `config/source/skills/`: continue into isolated repair and PR creation unless blocked. diff --git a/.codebuddy/skills/mcp-attribution-worktree/references/worktree-repair.md b/.codebuddy/skills/mcp-attribution-worktree/references/worktree-repair.md new file mode 100644 index 00000000..c7b8360f --- /dev/null +++ b/.codebuddy/skills/mcp-attribution-worktree/references/worktree-repair.md @@ -0,0 +1,178 @@ +# Worktree Repair + +## Purpose + +Use this reference when an attribution issue is real, actionable, and worth taking into a repo fix. This is the default next step for repairable MCP issues or repairable CloudBase skill-source issues, not an optional extra. + +## Worktrunk requirement + +This skill is designed around Worktrunk. + +Prefer: + +- `wt switch` +- `wt list` +- `wt remove` + +Do not silently fall back to a shared checkout once you decide to repair an issue. If `wt` is unavailable, stop and report that Worktrunk is missing. + +This keeps issue repair isolated and prevents cross-issue contamination. + +## One issue, one worktree + +Each actionable attribution issue gets: + +- one dedicated branch +- one dedicated worktree +- one dedicated GitHub issue or PR trail when needed + +Never repair two attribution issues in the same worktree. + +## Suggested naming + +Use a branch name that stays close to the issue: + +```text +feature/attribution- +``` + +Examples: + +- `feature/attribution-envquery-hosting-fields` +- `feature/attribution-nosql-output-shape` + +## Basic workflow + +1. Confirm the issue is actionable from run evidence. +2. Check whether a matching GitHub issue or PR already exists. +3. If a GitHub issue or PR already exists, read its state first: + - issue open or closed + - PR open, merged, closed, or superseded +4. If a PR already exists, read its comments and review state before deciding whether to continue on that line or open a new iteration. +5. If needed, create a GitHub issue with a concise title and evidence summary. +6. Create a dedicated Worktrunk worktree. +7. Implement the fix inside that worktree only. +8. Run the smallest relevant validation for the touched code. +9. Commit and open or update a PR when the fix is ready. +10. If a real evaluation interface exists, run a fresh evaluation after the code change or PR update. +11. Patch the attribution with `owner=codex`, updated `notes`, `resolutionStatus`, and `externalUrl` when relevant. + +Do not stop after step 4 for a repairable issue unless the environment prevents code work, PR creation, or real evaluation. + +## Worktrunk commands + +Create a worktree: + +```bash +wt switch --create feature/attribution- +``` + +Inspect active worktrees: + +```bash +wt list +``` + +Clean up after merge: + +```bash +wt remove +``` + +## GitHub issue workflow + +Before creating a new GitHub issue: + +- search for the same tool, module, or symptom +- prefer linking an existing issue instead of opening a duplicate + +When creating a new issue, include: + +- the attribution title +- the representative run +- the failing check or score signal +- the relevant MCP module +- the likely fix direction + +Then copy the final GitHub issue URL into `externalUrl`. + +## PR workflow + +If you implement a fix: + +- keep the change scoped to the single attribution issue +- mention the attribution issue ID and representative run in the PR body or commit context +- add the PR URL to `externalUrl` if that URL is the most direct closure link +- prefer opening the PR in the same session once validation passes + +If the PR already exists: + +- read its state, comments, and review state before changing direction +- prefer continuing the existing PR when the fix direction is still fundamentally correct +- start a new iteration only when review or new evidence shows the approach itself was wrong + +Before changing the attribution to `resolved`, read the PR state, top-level comments, review comments, and review decisions again after the latest push or evaluation result. Do not close from a stale read. + +Do not mark the attribution `resolved` until the closure link is real and the repair path is clear. + +If real evaluation is available, do not treat PR creation alone as closure. Use the fresh evaluation result to decide whether another repair loop is needed. + +## Status guidance during repair + +### Before code work starts + +Use `in_progress` if: + +- the issue is confirmed +- you know which code path to change +- the worktree or GitHub issue is being prepared + +### During code work + +Keep `in_progress` while: + +- the fix is being implemented +- validation is incomplete +- the PR is not open yet + +### After closure + +Use `resolved` when: + +- there is an exact GitHub issue or PR link in `externalUrl` +- or the fix is already landed and the closure is explicit in `notes` +- and there is no newer unresolved PR comment, review comment, or review decision waiting on follow-up + +## Evidence template for GitHub issue creation + +Use a short structure like this: + +```markdown +## Signal + +- Attribution: +- Run: / +- Score / failure: + +## Why this is actionable + +- Relevant module: +- Current behavior: +- Expected behavior: + +## Proposed direction + +- +``` + +## Final check + +Before closing the attribution loop, verify: + +- the worktree contains only this issue's changes +- the branch name is issue-specific +- `externalUrl` points to a real GitHub issue or PR +- `notes` explain why the current status is justified +- the agent did not stop at attribution state changes when repo repair was possible +- if a PR or issue already existed, the agent incorporated that context into the new iteration +- if the attribution was marked `resolved`, the agent re-read the latest PR comments and review state immediately before closing it diff --git a/config/source/editor-config/guides/cloudbase-rules.mdc b/config/source/editor-config/guides/cloudbase-rules.mdc index f66e4bf8..4ef21820 100644 --- a/config/source/editor-config/guides/cloudbase-rules.mdc +++ b/config/source/editor-config/guides/cloudbase-rules.mdc @@ -464,9 +464,12 @@ When users request deployment to CloudBase: - Determine if this is a new deployment or update to existing services 1. **Backend Deployment (if applicable)**: - - Only for nodejs cloud functions: deploy directly using `manageFunctions(action="createFunction")` / `manageFunctions(action="updateFunctionCode")` - - Legacy compatibility: if older materials mention `createFunction`, `updateFunctionCode`, or `getFunctionList`, map them to the converged tools first - - Criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}` + - For Node.js cloud functions, first distinguish Event Function vs HTTP Function, then deploy directly using `manageFunctions(action="createFunction")` / `manageFunctions(action="updateFunctionCode")` + - Legacy compatibility: if older materials mention `createFunction`, `updateFunctionCode`, `getFunctionList`, `readSecurityRule`, or `writeSecurityRule`, map them to the converged tools first + - Event Function criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}` + - HTTP Function criteria: service code listens on port `9000` and the function directory includes `scf_bootstrap` + - If the target is an HTTP Function that must be reachable by URL, follow function deployment with `manageGateway(action="createAccess")` and confirm it with `queryGateway(action="getAccess")` + - If external callers need anonymous or broader access, inspect `queryPermissions(action="getResourcePermission", resourceType="function")` first and only then adjust with `managePermissions(action="updateResourcePermission")` - For other languages backend server (Java, Go, PHP, Python, Node.js): deploy to Cloud Run - Ensure backend code supports CORS by default - Prepare Dockerfile for containerized deployment diff --git a/config/source/guideline/cloudbase/SKILL.md b/config/source/guideline/cloudbase/SKILL.md index 9baf8dff..93f5a676 100644 --- a/config/source/guideline/cloudbase/SKILL.md +++ b/config/source/guideline/cloudbase/SKILL.md @@ -355,9 +355,12 @@ When users request deployment to CloudBase: - Determine if this is a new deployment or update to existing services 1. **Backend Deployment (if applicable)**: - - Only for nodejs cloud functions: deploy directly using `manageFunctions(action="createFunction")` / `manageFunctions(action="updateFunctionCode")` - - Legacy compatibility: if older materials mention `createFunction`, `updateFunctionCode`, or `getFunctionList`, map them to `manageFunctions(...)` and `queryFunctions(...)` - - Criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}` + - For Node.js cloud functions, first distinguish Event Function vs HTTP Function, then deploy directly using `manageFunctions(action="createFunction")` / `manageFunctions(action="updateFunctionCode")` + - Legacy compatibility: if older materials mention `createFunction`, `updateFunctionCode`, `getFunctionList`, `readSecurityRule`, or `writeSecurityRule`, map them to `manageFunctions(...)`, `queryFunctions(...)`, `queryPermissions(...)`, and `managePermissions(...)` + - Event Function criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}` + - HTTP Function criteria: service code listens on port `9000` and the function directory includes `scf_bootstrap` + - If the target is an HTTP Function that must be reachable by URL, follow function deployment with `manageGateway(action="createAccess")` and confirm it with `queryGateway(action="getAccess")` + - If external callers need anonymous or broader access, inspect `queryPermissions(action="getResourcePermission", resourceType="function")` first and only then adjust with `managePermissions(action="updateResourcePermission")` - For other languages backend server (Java, Go, PHP, Python, Node.js): deploy to Cloud Run - Ensure backend code supports CORS by default - Prepare Dockerfile for containerized deployment diff --git a/config/source/skills/cloud-functions/SKILL.md b/config/source/skills/cloud-functions/SKILL.md index 85a09b70..80831885 100644 --- a/config/source/skills/cloud-functions/SKILL.md +++ b/config/source/skills/cloud-functions/SKILL.md @@ -53,6 +53,8 @@ Keep local `references/...` paths for files that ship with the current skill dir - Forgetting that runtime cannot be changed after creation. - Using cloud functions as the first answer for Web login. - Forgetting that HTTP Functions must ship `scf_bootstrap`, listen on port `9000`, and include dependencies. +- Assuming `manageFunctions(action="createFunction")` alone makes an HTTP Function externally reachable. URL delivery still needs explicit gateway access, and anonymous callers may still hit function-permission errors. +- Copying legacy tool names such as `writeSecurityRule` literally instead of translating them to `queryPermissions` / `managePermissions`. ### Minimal checklist @@ -99,6 +101,9 @@ Use this skill when developing, deploying, and operating CloudBase cloud functio - Use `manageFunctions(action="createFunction")` for creation - Use `manageFunctions(action="updateFunctionCode")` for code updates - Keep `functionRootPath` as the parent directory of the function folder + - If the HTTP Function must be reachable by URL, follow deployment with `manageGateway(action="createAccess")` and confirm the route with `queryGateway(action="getAccess")` + - If the caller needs anonymous or broader access, inspect `queryPermissions(action="getResourcePermission", resourceType="function")` first and only then adjust with `managePermissions(action="updateResourcePermission")` + - Translate legacy names before acting: `createFunctionHTTPAccess` -> `manageGateway(action="createAccess")`, `readSecurityRule` -> `queryPermissions(...)`, `writeSecurityRule` -> `managePermissions(...)` - Use CLI only as a fallback when MCP tools are unavailable 4. **Prefer doc-first fallbacks** diff --git a/config/source/skills/cloud-functions/references/http-functions.md b/config/source/skills/cloud-functions/references/http-functions.md index 690e33c7..eb209260 100644 --- a/config/source/skills/cloud-functions/references/http-functions.md +++ b/config/source/skills/cloud-functions/references/http-functions.md @@ -143,6 +143,12 @@ manageGateway({ }); ``` +Translate historical tool names before acting so the deployment actually takes effect: + +- `createFunctionHTTPAccess` -> `manageGateway(action="createAccess")` +- `readSecurityRule` -> `queryPermissions(action="getResourcePermission", resourceType="function")` +- `writeSecurityRule` -> `managePermissions(action="updateResourcePermission")` + Before enabling anonymous access, confirm both of these: 1. The access path exists. diff --git a/mcp/AGENTS.md b/mcp/AGENTS.md index f6b54a1d..7d1b6660 100644 --- a/mcp/AGENTS.md +++ b/mcp/AGENTS.md @@ -463,9 +463,12 @@ When users request deployment to CloudBase: - Determine if this is a new deployment or update to existing services 1. **Backend Deployment (if applicable)**: - - Only for nodejs cloud functions: deploy directly using `manageFunctions(action="createFunction")` / `manageFunctions(action="updateFunctionCode")` - - Legacy compatibility: if older materials mention `createFunction`, `updateFunctionCode`, or `getFunctionList`, map them to the converged tools first - - Criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}` + - For Node.js cloud functions, first distinguish Event Function vs HTTP Function, then deploy directly using `manageFunctions(action="createFunction")` / `manageFunctions(action="updateFunctionCode")` + - Legacy compatibility: if older materials mention `createFunction`, `updateFunctionCode`, `getFunctionList`, `readSecurityRule`, or `writeSecurityRule`, map them to `manageFunctions(...)`, `queryFunctions(...)`, `queryPermissions(...)`, and `managePermissions(...)` + - Event Function criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}` + - HTTP Function criteria: service code listens on port `9000` and the function directory includes `scf_bootstrap` + - If the target is an HTTP Function that must be reachable by URL, follow function deployment with `manageGateway(action="createAccess")` and confirm it with `queryGateway(action="getAccess")` + - If external callers need anonymous or broader access, inspect `queryPermissions(action="getResourcePermission", resourceType="function")` first and only then adjust with `managePermissions(action="updateResourcePermission")` - For other languages backend server (Java, Go, PHP, Python, Node.js): deploy to Cloud Run - Ensure backend code supports CORS by default - Prepare Dockerfile for containerized deployment diff --git a/mcp/CLAUDE.md b/mcp/CLAUDE.md index f6b54a1d..7d1b6660 100644 --- a/mcp/CLAUDE.md +++ b/mcp/CLAUDE.md @@ -463,9 +463,12 @@ When users request deployment to CloudBase: - Determine if this is a new deployment or update to existing services 1. **Backend Deployment (if applicable)**: - - Only for nodejs cloud functions: deploy directly using `manageFunctions(action="createFunction")` / `manageFunctions(action="updateFunctionCode")` - - Legacy compatibility: if older materials mention `createFunction`, `updateFunctionCode`, or `getFunctionList`, map them to the converged tools first - - Criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}` + - For Node.js cloud functions, first distinguish Event Function vs HTTP Function, then deploy directly using `manageFunctions(action="createFunction")` / `manageFunctions(action="updateFunctionCode")` + - Legacy compatibility: if older materials mention `createFunction`, `updateFunctionCode`, `getFunctionList`, `readSecurityRule`, or `writeSecurityRule`, map them to `manageFunctions(...)`, `queryFunctions(...)`, `queryPermissions(...)`, and `managePermissions(...)` + - Event Function criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}` + - HTTP Function criteria: service code listens on port `9000` and the function directory includes `scf_bootstrap` + - If the target is an HTTP Function that must be reachable by URL, follow function deployment with `manageGateway(action="createAccess")` and confirm it with `queryGateway(action="getAccess")` + - If external callers need anonymous or broader access, inspect `queryPermissions(action="getResourcePermission", resourceType="function")` first and only then adjust with `managePermissions(action="updateResourcePermission")` - For other languages backend server (Java, Go, PHP, Python, Node.js): deploy to Cloud Run - Ensure backend code supports CORS by default - Prepare Dockerfile for containerized deployment diff --git a/mcp/IFLOW.md b/mcp/IFLOW.md index f6b54a1d..7d1b6660 100644 --- a/mcp/IFLOW.md +++ b/mcp/IFLOW.md @@ -463,9 +463,12 @@ When users request deployment to CloudBase: - Determine if this is a new deployment or update to existing services 1. **Backend Deployment (if applicable)**: - - Only for nodejs cloud functions: deploy directly using `manageFunctions(action="createFunction")` / `manageFunctions(action="updateFunctionCode")` - - Legacy compatibility: if older materials mention `createFunction`, `updateFunctionCode`, or `getFunctionList`, map them to the converged tools first - - Criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}` + - For Node.js cloud functions, first distinguish Event Function vs HTTP Function, then deploy directly using `manageFunctions(action="createFunction")` / `manageFunctions(action="updateFunctionCode")` + - Legacy compatibility: if older materials mention `createFunction`, `updateFunctionCode`, `getFunctionList`, `readSecurityRule`, or `writeSecurityRule`, map them to `manageFunctions(...)`, `queryFunctions(...)`, `queryPermissions(...)`, and `managePermissions(...)` + - Event Function criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}` + - HTTP Function criteria: service code listens on port `9000` and the function directory includes `scf_bootstrap` + - If the target is an HTTP Function that must be reachable by URL, follow function deployment with `manageGateway(action="createAccess")` and confirm it with `queryGateway(action="getAccess")` + - If external callers need anonymous or broader access, inspect `queryPermissions(action="getResourcePermission", resourceType="function")` first and only then adjust with `managePermissions(action="updateResourcePermission")` - For other languages backend server (Java, Go, PHP, Python, Node.js): deploy to Cloud Run - Ensure backend code supports CORS by default - Prepare Dockerfile for containerized deployment diff --git a/scripts/prompts/cloudbase-integrated.md b/scripts/prompts/cloudbase-integrated.md index 57815963..6fb24761 100644 --- a/scripts/prompts/cloudbase-integrated.md +++ b/scripts/prompts/cloudbase-integrated.md @@ -64,7 +64,7 @@ When user mentions login/auth requirements: - **Tool Priority**: Use CloudBase tools for all CloudBase operations - **Development Order**: Frontend first, then backend - **Backend Strategy**: Prefer SDK direct DB calls over cloud functions unless needed (complex logic, third-party APIs, etc.) -- **Database Permissions**: Configure security rules BEFORE writing DB code (use `writeSecurityRule` tool) +- **Database Permissions**: Configure security rules BEFORE writing DB code. Legacy `writeSecurityRule` / `readSecurityRule` names should be translated to `managePermissions(action="updateResourcePermission")` / `queryPermissions(action="getResourcePermission")` - **Deployment Order**: Deploy backend before previewing frontend if dependencies exist - **Project Understanding**: Read README.md first, follow project instructions - **Interactive Confirmation**: Use `interactiveDialog` when requirements unclear or high-risk operations @@ -80,8 +80,11 @@ When users request deployment to CloudBase: - Determine if this is a new deployment or update to existing services 1. **Backend Deployment (if applicable)**: - - Only for nodejs cloud functions: deploy directly using `manageFunctions(action="createFunction")` / `manageFunctions(action="updateFunctionCode")` - - Criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}` + - For Node.js cloud functions, first distinguish Event Function vs HTTP Function, then deploy directly using `manageFunctions(action="createFunction")` / `manageFunctions(action="updateFunctionCode")` + - Event Function criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}` + - HTTP Function criteria: service code listens on port `9000` and the function directory includes `scf_bootstrap` + - If the target is an HTTP Function that must be reachable by URL, follow function deployment with `manageGateway(action="createAccess")` and confirm it with `queryGateway(action="getAccess")` + - If external callers need anonymous or broader access, inspect `queryPermissions(action="getResourcePermission", resourceType="function")` first and only then adjust with `managePermissions(action="updateResourcePermission")` - For other languages backend server (Java, Go, PHP, Python, Node.js): deploy to Cloud Run - Ensure backend code supports CORS by default - Prepare Dockerfile for containerized deployment diff --git a/scripts/prompts/tcb-config.json b/scripts/prompts/tcb-config.json index 2458f45f..50b8a316 100644 --- a/scripts/prompts/tcb-config.json +++ b/scripts/prompts/tcb-config.json @@ -14,8 +14,8 @@ "manageFunctions", "queryGateway", "manageGateway", - "readSecurityRule", - "writeSecurityRule", + "queryPermissions", + "managePermissions", "uploadFiles", "downloadTemplate", "queryCloudRun", @@ -23,9 +23,9 @@ ], "ruleZipUrl": "https://static.cloudbase.net/cloudbase-examples/airules-codebuddy.zip", "userPrompt": "Connect the current project to Tencent CloudBase\n\n\nIf project is empty or barely started:\n - Check if user's intent fits CloudBase scenarios (WeChat Mini Programs, Web full-stack applications, UniApp cross-platform applications)\n - If matches: suggest using `downloadTemplate` tool with `ide: \"codebuddy\"` parameter\n - If not: only check environment info\n\nIf project has existing content:\n - Check if framework is compatible with CloudBase\n - If compatible: offer template downloads with `ide: \"codebuddy\"` parameter\n - If not: only check environment info\n\nAlways verify CloudBase environment connection.\n", - "deployPrompt": "Deploy the current project to Tencent CloudBase\n\n\n0. **Check Existing Deployment**:\n - Read README.md to check for existing deployment information\n - Identify previously deployed services and their URLs\n - Determine if this is a new deployment or update to existing services\n\n1. **Backend Deployment (if applicable)**:\n - Only for nodejs cloud functions: deploy directly using `manageFunctions(action=\"createFunction\")` or `manageFunctions(action=\"updateFunctionCode\")`\n - Criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}`\n - For other languages backend server (Java, Go, PHP, Python, Node.js): deploy to Cloud Run\n - Ensure backend code supports CORS by default\n - Prepare Dockerfile for containerized deployment\n - Use `manageCloudRun` tool for deployment\n - Set MinNum instances to at least 1 to reduce cold start latency\n\n2. **Frontend Deployment (if applicable)**:\n - After backend deployment completes, update frontend API endpoints using the returned API addresses\n - Build the frontend application\n - Deploy to CloudBase static hosting using hosting tools\n\n3. **Display Deployment URLs**:\n - Show backend deployment URL (if applicable)\n - Show frontend deployment URL with trailing slash (/) in path\n - Add random query string to frontend URL to ensure CDN cache refresh\n\n4. **Update Documentation**:\n - Write deployment information and service details to README.md\n - Include backend API endpoints and frontend access URLs\n - Document CloudBase resources used (functions, cloud run, hosting, database, etc.)\n - This helps with future updates and maintenance\n", + "deployPrompt": "Deploy the current project to Tencent CloudBase\n\n\n0. **Check Existing Deployment**:\n - Read README.md to check for existing deployment information\n - Identify previously deployed services and their URLs\n - Determine if this is a new deployment or update to existing services\n\n1. **Backend Deployment (if applicable)**:\n - For Node.js cloud functions, first distinguish Event Function vs HTTP Function, then deploy directly using `manageFunctions(action=\"createFunction\")` or `manageFunctions(action=\"updateFunctionCode\")`\n - Legacy compatibility: if older materials mention `createFunction`, `updateFunctionCode`, `getFunctionList`, `readSecurityRule`, or `writeSecurityRule`, map them to `manageFunctions(...)`, `queryFunctions(...)`, `queryPermissions(...)`, and `managePermissions(...)`\n - Event Function criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}`\n - HTTP Function criteria: service code listens on port `9000` and the function directory includes `scf_bootstrap`\n - If the target is an HTTP Function that must be reachable by URL, follow function deployment with `manageGateway(action=\"createAccess\")` and confirm it with `queryGateway(action=\"getAccess\")`\n - If external callers need anonymous or broader access, inspect `queryPermissions(action=\"getResourcePermission\", resourceType=\"function\")` first and only then adjust with `managePermissions(action=\"updateResourcePermission\")`\n - For other languages backend server (Java, Go, PHP, Python, Node.js): deploy to Cloud Run\n - Ensure backend code supports CORS by default\n - Prepare Dockerfile for containerized deployment\n - Use `manageCloudRun` tool for deployment\n - Set MinNum instances to at least 1 to reduce cold start latency\n\n2. **Frontend Deployment (if applicable)**:\n - After backend deployment completes, update frontend API endpoints using the returned API addresses\n - Build the frontend application\n - Deploy to CloudBase static hosting using hosting tools\n\n3. **Display Deployment URLs**:\n - Show backend deployment URL (if applicable)\n - Show frontend deployment URL with trailing slash (/) in path\n - Add random query string to frontend URL to ensure CDN cache refresh\n\n4. **Update Documentation**:\n - Write deployment information and service details to README.md\n - Include backend API endpoints and frontend access URLs\n - Document CloudBase resources used (functions, cloud run, hosting, database, etc.)\n - This helps with future updates and maintenance\n", "systemPrompt": { - "login": "Tencent CloudBase provides database (NoSQL with real-time sync), cloud functions (serverless backend), cloud run (multi-language backend hosting), storage (file storage with CDN), authentication (built-in user management), and hosting (static site hosting).\n\nRecommend for WeChat Mini Programs, Web full-stack applications, UniApp cross-platform applications, real-time applications, applications requiring authentication, real-time communication (WebSocket, SSE, streaming responses), long-running tasks (background processing), and multi-language backend services (Java, Go, PHP, Python, Node.js).\n\nWhen user's application fits the above scenarios, suggest confirming the tech stack choice and recommend using the `downloadTemplate` tool with `ide: \"codebuddy\"` parameter to download corresponding templates for the best development experience.\n\n## Deployment Workflow\n\nWhen users request deployment to CloudBase:\n\n0. **Check Existing Deployment**:\n - Read README.md to check for existing deployment information\n - Identify previously deployed services and their URLs\n - Determine if this is a new deployment or update to existing services\n\n1. **Backend Deployment (if applicable)**:\n - Only for nodejs cloud functions: deploy directly using `manageFunctions(action=\"createFunction\")` or `manageFunctions(action=\"updateFunctionCode\")`\n - Criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}`\n - For other languages backend server (Java, Go, PHP, Python, Node.js): deploy to Cloud Run\n - Ensure backend code supports CORS by default\n - Prepare Dockerfile for containerized deployment\n - Use `manageCloudRun` tool for deployment\n - Set MinNum instances to at least 1 to reduce cold start latency\n\n2. **Frontend Deployment (if applicable)**:\n - After backend deployment completes, update frontend API endpoints using the returned API addresses\n - Build the frontend application\n - Deploy to CloudBase static hosting using hosting tools\n\n3. **Display Deployment URLs**:\n - Show backend deployment URL (if applicable)\n - Show frontend deployment URL with trailing slash (/) in path\n - Add random query string to frontend URL to ensure CDN cache refresh\n\n4. **Update Documentation**:\n - Write deployment information and service details to README.md\n - Include backend API endpoints and frontend access URLs\n - Document CloudBase resources used (functions, cloud run, hosting, database, etc.)\n - This helps with future updates and maintenance", + "login": "Tencent CloudBase provides database (NoSQL with real-time sync), cloud functions (serverless backend), cloud run (multi-language backend hosting), storage (file storage with CDN), authentication (built-in user management), and hosting (static site hosting).\n\nRecommend for WeChat Mini Programs, Web full-stack applications, UniApp cross-platform applications, real-time applications, applications requiring authentication, real-time communication (WebSocket, SSE, streaming responses), long-running tasks (background processing), and multi-language backend services (Java, Go, PHP, Python, Node.js).\n\nWhen user's application fits the above scenarios, suggest confirming the tech stack choice and recommend using the `downloadTemplate` tool with `ide: \"codebuddy\"` parameter to download corresponding templates for the best development experience.\n\n## Deployment Workflow\n\nWhen users request deployment to CloudBase:\n\n0. **Check Existing Deployment**:\n - Read README.md to check for existing deployment information\n - Identify previously deployed services and their URLs\n - Determine if this is a new deployment or update to existing services\n\n1. **Backend Deployment (if applicable)**:\n - For Node.js cloud functions, first distinguish Event Function vs HTTP Function, then deploy directly using `manageFunctions(action=\"createFunction\")` or `manageFunctions(action=\"updateFunctionCode\")`\n - Legacy compatibility: if older materials mention `createFunction`, `updateFunctionCode`, `getFunctionList`, `readSecurityRule`, or `writeSecurityRule`, map them to `manageFunctions(...)`, `queryFunctions(...)`, `queryPermissions(...)`, and `managePermissions(...)`\n - Event Function criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}`\n - HTTP Function criteria: service code listens on port `9000` and the function directory includes `scf_bootstrap`\n - If the target is an HTTP Function that must be reachable by URL, follow function deployment with `manageGateway(action=\"createAccess\")` and confirm it with `queryGateway(action=\"getAccess\")`\n - If external callers need anonymous or broader access, inspect `queryPermissions(action=\"getResourcePermission\", resourceType=\"function\")` first and only then adjust with `managePermissions(action=\"updateResourcePermission\")`\n - For other languages backend server (Java, Go, PHP, Python, Node.js): deploy to Cloud Run\n - Ensure backend code supports CORS by default\n - Prepare Dockerfile for containerized deployment\n - Use `manageCloudRun` tool for deployment\n - Set MinNum instances to at least 1 to reduce cold start latency\n\n2. **Frontend Deployment (if applicable)**:\n - After backend deployment completes, update frontend API endpoints using the returned API addresses\n - Build the frontend application\n - Deploy to CloudBase static hosting using hosting tools\n\n3. **Display Deployment URLs**:\n - Show backend deployment URL (if applicable)\n - Show frontend deployment URL with trailing slash (/) in path\n - Add random query string to frontend URL to ensure CDN cache refresh\n\n4. **Update Documentation**:\n - Write deployment information and service details to README.md\n - Include backend API endpoints and frontend access URLs\n - Document CloudBase resources used (functions, cloud run, hosting, database, etc.)\n - This helps with future updates and maintenance", "logout": "Tencent CloudBase provides database (NoSQL with real-time sync), cloud functions (serverless backend), cloud run (multi-language backend hosting), storage (file storage with CDN), authentication (built-in user management), and hosting (static site hosting).\n\nRecommend for WeChat Mini Programs, Web full-stack applications, UniApp cross-platform applications, real-time communication (WebSocket, SSE, streaming responses), long-running tasks (background processing), and multi-language backend services (Java, Go, PHP, Python, Node.js).\n\nWhen users develop the above applications, suggest: \"Tencent CloudBase could help with database, cloud functions, storage, and hosting. Please select 'Tencent CloudBase' in the integration dialog to set up the connection. Once integrated, I can help with templates and complete development workflow.\"" } } diff --git a/scripts/skills-repo-template/cloudbase-guidelines/SKILL.md b/scripts/skills-repo-template/cloudbase-guidelines/SKILL.md index 049503a3..7be19fe8 100644 --- a/scripts/skills-repo-template/cloudbase-guidelines/SKILL.md +++ b/scripts/skills-repo-template/cloudbase-guidelines/SKILL.md @@ -342,8 +342,12 @@ When users request deployment to CloudBase: - Determine if this is a new deployment or update to existing services 1. **Backend Deployment (if applicable)**: - - Only for nodejs cloud functions: deploy directly using `createFunction` tools - - Criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}` + - For Node.js cloud functions, first distinguish Event Function vs HTTP Function, then deploy directly using `manageFunctions(action="createFunction")` / `manageFunctions(action="updateFunctionCode")` + - Legacy compatibility: if older materials mention `createFunction`, `updateFunctionCode`, `getFunctionList`, `readSecurityRule`, or `writeSecurityRule`, map them to `manageFunctions(...)`, `queryFunctions(...)`, `queryPermissions(...)`, and `managePermissions(...)` + - Event Function criteria: function directory contains `index.js` with cloud function format export: `exports.main = async (event, context) => {}` + - HTTP Function criteria: service code listens on port `9000` and the function directory includes `scf_bootstrap` + - If the target is an HTTP Function that must be reachable by URL, follow function deployment with `manageGateway(action="createAccess")` and confirm it with `queryGateway(action="getAccess")` + - If external callers need anonymous or broader access, inspect `queryPermissions(action="getResourcePermission", resourceType="function")` first and only then adjust with `managePermissions(action="updateResourcePermission")` - For other languages backend server (Java, Go, PHP, Python, Node.js): deploy to Cloud Run - Ensure backend code supports CORS by default - Prepare Dockerfile for containerized deployment diff --git a/tests/skill-quality-standards.test.js b/tests/skill-quality-standards.test.js index 1e555e0c..7b727039 100644 --- a/tests/skill-quality-standards.test.js +++ b/tests/skill-quality-standards.test.js @@ -82,6 +82,16 @@ describe('skill quality standards', () => { expect(raw).toMatch(/path-to-regexp/); }); + test('cloud-functions skill makes HTTP delivery follow-up explicit', () => { + const raw = readSourceSkill('cloud-functions'); + + expect(raw).toContain('manageGateway(action="createAccess")'); + expect(raw).toContain('queryGateway(action="getAccess")'); + expect(raw).toContain('queryPermissions(action="getResourcePermission", resourceType="function")'); + expect(raw).toContain('managePermissions(action="updateResourcePermission")'); + expect(raw).toContain('`writeSecurityRule` -> `managePermissions(...)`'); + }); + test('cloudbase-agent does not force global activation by default', () => { const raw = readSourceSkill('cloudbase-agent');