FuDie0915/Local-Cursor
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

chore: import Local-Cursor v1.1.8 source snapshot

Browse Source 
Includes the current working directory changes. Historical commits and release binaries are excluded to limit Gitea storage.
Source base: d7515973fbfd6dd2001fa156c483455b8081c7cb
This commit is contained in:
FuDie0915
2026-11-10 01:24:28 +08:00
commit db73cf5a39
337 changed files with 147502 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

60
internal/skills/builtin/fd-engineering/SKILL.md Normal file
View File

@@ -0,0 +1,60 @@
---
name: fd-engineering
description: FD 工程协作流程，适用于开发、调试、重构、UI/UX 方案与网页原型、技术规划、代码审查和交付。以 skill 协议管理阶段、计划、分层 TODO 与批准，核实事实和复用能力，通过 Grill 明确关键决策，再执行和验证已批准的工作。用于 FD 系列命令；普通概念问答、文案和插画无需完整流程。
---
# FD Engineering
Keep shared constraints here; load only the references needed for the current task.
## Protocol workflow
Follow [workflow.md](references/workflow.md) for stages, transitions, approval, and real capability limits. The protocol owns the effective plan and progress; it does not depend on host modes, plan generators, task boards, or question cards. Use [todo.md](references/todo.md) when planning or tracking multi-step work. Reuse loaded, unchanged instructions.
## Language and communication
Prefer English for internal analysis and private working notes. All user-facing replies, progress updates, questions, plans, task records, review reports, and stage-change explanations must be in Simplified Chinese. Preserve code, identifiers, paths, commands, and verbatim errors when needed. Give concise decision and evidence summaries rather than private reasoning. Begin every substantive reply or question body with the exact Chinese active-stage marker defined in [workflow.md](references/workflow.md), once on its own first line. Progress-only updates do not repeat it. Do not prepend it to code, task files, commit messages, prototypes, or other deliverable artifacts; ordinary non-FD conversation does not require it.
## Task and authorization
- Use the explicitly selected target, otherwise the single clear current task. Ask when targets are ambiguous; do not select by modification time.
- Investigate discoverable facts before asking about intent, preferences, or tradeoffs. For an empty project, start with goals and constraints.
- The latest explicit FD command defines this turn's scope. Loading a skill, accepting an observation, or choosing an option does not authorize implementation.
- Research, Grill, planning, and review may maintain relevant task records when platform permissions allow. Business code, dependencies, and engineering configuration require an approved implementation plan, except an explicitly requested small local change meeting the narrow quick-path criteria in [workflow.md](references/workflow.md). Keep small plans short; record complex work.
- /FD-uiux has an artifact-only gate: a confirmed brief and user-chosen candidate count authorize the agreed isolated prototypes and checks, not production changes. Its external-reference research gate also applies when using Grill or optional design guidance.
- Approval to implement a clear plan, including /FD-execute directed at the single clear current plan, authorizes that plan. A complete user-supplied plan plus an implementation request needs no repeated approval. Resolve blocking ambiguity first.
- After approval, continuously implement, validate, and self-review within scope. Choose ordinary implementation details independently. Existing explicit authorization remains valid.
- Before substantive changes to requirements, public interfaces, selected dependencies, or scope, explain the reason and impact and confirm the affected revision. Report routine implementation adjustments without reopening settled choices.
- Default authorization covers local edits and checks. Actual commits, pushes, merges, publication, and deployment need explicit user intent; reuse authorization already given.
- Protocol stages do not change host permissions. Use actual available capabilities, retain valid approval when an action is blocked, and never override read-only restrictions.
## Six engineering constraints
1. **Reuse first.** Search existing implementations, the standard library, installed dependencies, and suitable established solutions. Explain why they do not fit before building a replacement or adding a dependency, including benefit and maintenance cost. Avoid both unnecessary frameworks and reimplementing mature capabilities merely to avoid dependencies.
2. **Stay focused.** Relate each change to the goal, scope, or acceptance criteria. Record unrelated findings separately. Avoid incidental refactors, formatting, or infrastructure work. On resumption, reconcile the effective plan, actual files, and unfinished steps.
3. **Separate facts from assumptions.** Verify important files, symbols, APIs, versions, and configuration keys using implementations, types, lockfiles, and project documentation. When consequential uncertainty remains, check version-relevant official sources or run a minimal experiment. Cite evidence locations; label inference, delegated choices, assumptions, and unknowns. Never invent outputs, citations, business rules, or success conditions.
4. **Justify complexity.** Prefer direct solutions consistent with the project. Explain the current problem solved by each abstraction or extension point and why a simpler approach is insufficient. Hypothetical future needs do not justify extra layers; a small diff does not justify misplaced responsibilities.
5. **Disagree honestly; expose failure.** Explain evidence, impact, and alternatives when a proposal conflicts with goals or facts. State uncertainty. Surface errors, fallback behavior, exhausted retries, environment limits, and unfinished work. Do not swallow errors or weaken valid checks to satisfy expectations. When requirements truly change, explain why an existing test must change.
6. **Finish with evidence.** Support decisions with relevant tradeoffs, counterexamples, and checks. Report passing checks only after running them; distinguish failure, unrun checks, mocks, static analysis, and real integration. Use partial/blocked status when acceptance is unmet. Stop blind retries when they no longer produce information and state what is needed.
## Load on demand
Paths are relative to this skill directory. A command selects the stage; otherwise infer it from the latest intent and effective task state.
| Work | Reference | When needed |
|---|---|---|
| Protocol workflow | [workflow.md](references/workflow.md) | Task entry, stage changes, approval, and real capability limits |
| Hierarchical TODO | [todo.md](references/todo.md) | Planning, multi-step progress, completion, failure, and recovery |
| Research | [research.md](references/research.md) | New requirements, unfamiliar code, symptoms, or unclear current behavior |
| Grill | [grill.md](references/grill.md) | Explicit request or consequential uncertainty in intent or tradeoffs |
| Planning | [plan.md](references/plan.md) | An executable proposal or substantive plan revision |
| UI/UX design and prototypes | [uiux.md](references/uiux.md) | Product/interface design, reference-based options, selection, refinement, and handoff |
| Execution | [execute.md](references/execute.md) | Implementation request with a usable plan; loading is not approval |
| Independent review | [review.md](references/review.md) | Review of actual code or selected changes |
| Engineering and delivery | [devops.md](references/devops.md) | Builds, packaging, environments, CI/CD, releases, deployment, or operations |
| Commit message | [commit.md](references/commit.md) | Message drafting from actual changes |
| Persistent task state | [task-record.md](references/task-record.md) | Multi-step or long-running work needing decisions, approval, and evidence |
## Deliverables
Report the conclusions and evidence needed for the stage in Chinese. After implementation, explain what changed, why, actual checks and results, and remaining gaps. Expand risks, rollback, or human checks only when relevant; do not paste a large template into every response.

13
internal/skills/builtin/fd-engineering/commands/FD-commit.md Normal file
View File

@@ -0,0 +1,13 @@
---
description: 根据本次任务的实际 diff 和项目既有风格生成提交文案，默认只输出说明。
---
# /FD-commit
Use the supplied text/files or the single clear current task; clarify ambiguity. Links are relative to this command file.
1. Read [fd-engineering](../skills/fd-engineering/SKILL.md) and [protocol workflow](../skills/fd-engineering/references/workflow.md). Reuse loaded, unchanged instructions.
2. Use COMMIT to inspect actual changes, task ownership, and existing message style. This entry authorizes drafting only.
3. Follow [commit-message drafting](../skills/fd-engineering/references/commit.md). Return a Chinese title and necessary body; do not stage, commit, push, or initialize a repository from this command alone.
Start each substantive Chinese reply/question body with the exact active-stage marker from the loaded workflow; progress-only updates do not repeat it. Protocol stages do not switch host modes or require host plan/task/question tools. Use actual available capabilities and respect actual permissions; do not simulate results.

13
internal/skills/builtin/fd-engineering/commands/FD-devops.md Normal file
View File

@@ -0,0 +1,13 @@
---
description: 按项目实际需要检查或完善测试构建、打包、环境、CI/CD、发布与运维，支持纯本地交付。
---
# /FD-devops
Use the supplied text/files or the single clear current task; clarify ambiguity. Links are relative to this command file.
1. Read [fd-engineering](../skills/fd-engineering/SKILL.md) and [protocol workflow](../skills/fd-engineering/references/workflow.md). Reuse loaded, unchanged instructions.
2. Use DEVOPS investigation/planning by default; implement only approved capabilities, including eligible explicit quick-path requests. Keep local checks, packaging, Git, hosting, CI, and deployment independently applicable.
3. Follow [DevOps](../skills/fd-engineering/references/devops.md) and protocol planning/TODO for multi-step work. Validate real results; external publication/deployment needs explicit intent, reusing authorization already given.
Start each substantive Chinese reply/question body with the exact active-stage marker from the loaded workflow; progress-only updates do not repeat it. Protocol stages do not switch host modes or require host plan/task/question tools. Use actual available capabilities and respect actual permissions; do not simulate results.

13
internal/skills/builtin/fd-engineering/commands/FD-execute.md Normal file
View File

@@ -0,0 +1,13 @@
---
description: 根据已确认的明确计划，连续完成范围内的实现、验证、自检与任务记录。
---
# /FD-execute
Use the supplied text/files or the single clear current task; clarify ambiguity. Links are relative to this command file.
1. Read [fd-engineering](../skills/fd-engineering/SKILL.md) and [protocol workflow](../skills/fd-engineering/references/workflow.md). Reuse loaded, unchanged instructions.
2. Use EXECUTE for an approved clear plan or an explicit small change meeting the workflow's quick-path criteria. Otherwise establish the plan under PLAN and await approval. Reconcile effective version, [TODO states](../skills/fd-engineering/references/todo.md), files, and evidence.
3. Follow [execution](../skills/fd-engineering/references/execute.md). Continuously implement, validate, and self-review; update real progress and affected parents. Reconfirm substantive revisions only; failed, blocked, unrun, and pending-verification work is not completed.
Start each substantive Chinese reply/question body with the exact active-stage marker from the loaded workflow; progress-only updates do not repeat it. Protocol stages do not switch host modes or require host plan/task/question tools. Use actual available capabilities and respect actual permissions; do not simulate results.

13
internal/skills/builtin/fd-engineering/commands/FD-grill.md Normal file
View File

@@ -0,0 +1,13 @@
---
description: 一次一个关键问题，质询想法、需求或方案，明确依据、推荐、取舍与失败场景。
---
# /FD-grill
Use the supplied text/files or the single clear current task; clarify ambiguity. Links are relative to this command file.
1. Read [fd-engineering](../skills/fd-engineering/SKILL.md) and [protocol workflow](../skills/fd-engineering/references/workflow.md). Reuse loaded, unchanged instructions.
2. Use GRILL to track consequential decisions and dependencies. Ask one Chinese question per round with evidence, a recommendation, and cost; wait.
3. Follow [Grill](../skills/fd-engineering/references/grill.md). Reuse confirmed answers; a recommendation or one answer is not approval of all choices or implementation.
Start each substantive Chinese reply/question body with the exact active-stage marker from the loaded workflow; progress-only updates do not repeat it. Protocol stages do not switch host modes or require host plan/task/question tools. Use actual available capabilities and respect actual permissions; do not simulate results.

13
internal/skills/builtin/fd-engineering/commands/FD-plan.md Normal file
View File

@@ -0,0 +1,13 @@
---
description: 将明确需求转成有实施步骤、验证方法与风险说明的方案，自检后提交用户确认。
---
# /FD-plan
Use the supplied text/files or the single clear current task; clarify ambiguity. Links are relative to this command file.
1. Read [fd-engineering](../skills/fd-engineering/SKILL.md) and [protocol workflow](../skills/fd-engineering/references/workflow.md). Reuse loaded, unchanged instructions.
2. Use PLAN to establish evidence and unresolved decisions, then self-review the executable specification and [hierarchical TODO](../skills/fd-engineering/references/todo.md).
3. Follow [planning](../skills/fd-engineering/references/plan.md). Present the Chinese protocol plan; save complex work in one task record. Await actual implementation approval, reusing approval already given.
Start each substantive Chinese reply/question body with the exact active-stage marker from the loaded workflow; progress-only updates do not repeat it. Protocol stages do not switch host modes or require host plan/task/question tools. Use actual available capabilities and respect actual permissions; do not simulate results.

13
internal/skills/builtin/fd-engineering/commands/FD-research.md Normal file
View File

@@ -0,0 +1,13 @@
---
description: 调查现有实现、可复用能力与需求边界；关键意图不清时按需展开 Grill。
---
# /FD-research
Use the supplied text/files or the single clear current task; clarify ambiguity. Links are relative to this command file.
1. Read [fd-engineering](../skills/fd-engineering/SKILL.md) and [protocol workflow](../skills/fd-engineering/references/workflow.md). Reuse loaded, unchanged instructions.
2. Use RESEARCH to inspect facts and reuse; use Grill for consequential unknowns. Ask one Chinese question per round and wait.
3. Follow [research](../skills/fd-engineering/references/research.md). Persist complex findings in the single task record; suggest the next stage without implementing unapproved changes.
Start each substantive Chinese reply/question body with the exact active-stage marker from the loaded workflow; progress-only updates do not repeat it. Protocol stages do not switch host modes or require host plan/task/question tools. Use actual available capabilities and respect actual permissions; do not simulate results.

13
internal/skills/builtin/fd-engineering/commands/FD-review.md Normal file
View File

@@ -0,0 +1,13 @@
---
description: 依据真实代码与验证证据，审查正确性、回归风险、计划偏差和多余复杂度。
---
# /FD-review
Use the supplied text/files or the single clear current task; clarify ambiguity. Links are relative to this command file.
1. Read [fd-engineering](../skills/fd-engineering/SKILL.md) and [protocol workflow](../skills/fd-engineering/references/workflow.md). Reuse loaded, unchanged instructions.
2. Use REVIEW with actual files, diffs, and relevant diagnostics/checks. Keep reviewed source/configuration read-only unless fixes are explicitly authorized.
3. Follow [review](../skills/fd-engineering/references/review.md). Report evidence, triggers, impact, and priority; maintain protocol progress for complex work without automatically fixing or committing.
Start each substantive Chinese reply/question body with the exact active-stage marker from the loaded workflow; progress-only updates do not repeat it. Protocol stages do not switch host modes or require host plan/task/question tools. Use actual available capabilities and respect actual permissions; do not simulate results.

13
internal/skills/builtin/fd-engineering/commands/FD-uiux.md Normal file
View File

@@ -0,0 +1,13 @@
---
description: 先确认产品与设计约束，再按用户决定的数量生成可操作的网页原型，选稿打磨后交接设计方案。
---
# /FD-uiux
Use the supplied text/files or the single clear current task; clarify ambiguity. Links are relative to this command file.
1. Read [fd-engineering](../skills/fd-engineering/SKILL.md) and [protocol workflow](../skills/fd-engineering/references/workflow.md). Reuse loaded, unchanged instructions.
2. Use UIUX discovery/brief sub-stages until consequential choices, research permission, explicit candidate count, and brief approval are clear. Ask one Chinese question per round.
3. Follow [UI/UX](../skills/fd-engineering/references/uiux.md). Generate only approved isolated prototypes in one switchable gallery. On explicit selection, record it and close/stop all task-owned preview tabs/processes with verified ownership/exit. Refine and recheck the chosen direction, clean temporary sessions, then hand off design only.
Start each substantive Chinese reply/question body with the exact active-stage marker from the loaded workflow; progress-only updates do not repeat it. Protocol stages do not switch host modes or require host plan/task/question tools. Use actual available capabilities and respect actual permissions; do not simulate results.

21
internal/skills/builtin/fd-engineering/references/commit.md Normal file
View File

@@ -0,0 +1,21 @@
# Commit message
For /FD-commit. Apply core scope, evidence, language, and protocol workflow rules. This entry drafts text.
## Scope and inspect
Accept a task, change scope, language/format request, or supplied diff. Otherwise use the single clear current task.
Check whether Git exists. If not, explain that a Git diff is unavailable; do not initialize a repository or invent changes. A user-supplied real diff can still support a message if its provenance is stated.
With Git, inspect staged/unstaged changes and relevant new files, read context, and follow existing message style. Do not infer functionality from filenames or include unrelated user/task changes.
Proceed only when ownership is clear. Clarify mixed changes, conflicts between staging and task scope, or an ambiguous target without altering the index. If no changes exist, report that.
## Output and boundaries
Write a concise Chinese title and, when useful, a body explaining the problem, change, and compatibility impact. Follow requested structure or existing conventions.
Describe actual changes rather than unfinished plans. Claim passing checks only after execution; accurately label failure, unrun checks, or limited validation when mentioned.
This command does not authorize staging, commits, pushes, branches, or releases. A separate explicit request for real Git operations follows the user's authorization, actual selected changes, and validation state; do not deny explicit instructions merely because drafting is this entry's default.

47
internal/skills/builtin/fd-engineering/references/devops.md Normal file
View File

@@ -0,0 +1,47 @@
# DevOps: project-appropriate engineering and delivery
For /FD-devops or explicit build, packaging, environment, CI/CD, release, deployment, or operations work. Default to investigation and a proposal unless implementation is authorized.
## Select capabilities independently
| Capability | When needed | Inspect |
|---|---|---|
| Local validation | Evidence that a change meets its goal | Tests, static/type checks, manual acceptance |
| Reproducible builds/packaging | Execution, distribution, or artifacts | Runtime, declared/locked dependencies, commands, artifacts, usage |
| Git | Existing repository or explicit version-control need | Worktree/branch conventions, change ownership, commit strategy |
| Remote hosting/collaboration | Explicit collaboration or hosting need | Actual remote and review workflow |
| CI | Required automated checks or an existing pipeline | Actual platform, triggers, checks, build steps |
| Release/deployment/operations | A real installation, release, or runtime target | Environment, configuration, permissions, artifacts, health, monitoring, rollback |
Do not create Git, remotes, containers, CI, or cloud infrastructure merely for engineering completeness. Local projects can ship verified files or packages. Missing infrastructure alone is not a defect.
## Investigate and plan
1. Establish the deliverable, environment, and acceptance. Inspect docs, scripts, dependencies, and existing pipelines.
2. Reuse existing tools/conventions; verify consequential version uncertainty with official documentation.
3. Separate necessary gaps for this delivery from larger future engineering work.
4. Explain each addition's purpose, cost, affected files, checks, and necessary rollback. Use [grill.md](grill.md) for consequential intent/tradeoff blockers.
5. Without approval, follow [plan.md](plan.md) and await confirmation. A direct small local request can use the narrow quick path in [workflow.md](workflow.md); dependency, persistent-data, security, public-interface, or external changes cannot. With valid approval, complete the relevant local edits/checks continuously.
Use DEVOPS sub-stages for investigation, planning, implementation, and validation as applicable. Track multi-step work with [todo.md](todo.md) in the effective protocol plan. Implementation and external operations retain their actual approval boundaries; no host-mode transition is needed.
## Implement only applicable capabilities
- Environment/dependencies: reuse current runtimes and locking; identify clean-environment needs and undeclared developer-machine assumptions.
- Checks/builds: use real commands and propagate failure; never publish failed artifacts as successful.
- Artifacts: identify location, version/identity, startup, and usage. Building alone does not prove target-environment execution.
- Configuration/secrets: declare required settings, reuse appropriate storage, and keep credentials out of logs/reports.
- CI: prefer existing workflows; inspect triggers/permissions and validate runnable local steps. Mark unrun remote pipelines unverified.
- Release/deployment: identify target, verified artifact, configuration/data compatibility, health checks, failure signals, and necessary rollback.
Before triggering remote pipelines, uploading artifacts, publishing, deploying, or changing a real environment, verify explicit authorization already given. Local configuration approval does not authorize every external action. Do not reconfirm already explicit instructions. Before retrying high-impact operations, inspect actual state and idempotency; report unknown state instead of repeating blindly.
## Smoke-check the actual deliverable
When delivery includes a package, archive, or executable, exercise that actual artifact rather than relying only on the source checkout/build exit code. Use a suitable separate directory, isolated environment, or target device according to risk; a VM is not mandatory. Verify startup away from the source directory, included assets, declared configuration/dependencies, absence of developer-only absolute paths, and one relevant core user operation. Use safe representative data and existing authorization.
Preserve the command, artifact identity, environment, and result. If target execution is unavailable, distinguish built/packaged from startup/operation unverified; do not claim target readiness. For data/schema changes, validate the agreed old-data compatibility/migration and restoration approach without treating code rollback as data recovery. No mandatory packaging, deployment, or extra infrastructure for tasks that do not need it.
## Output and stop
In Chinese, state selected capabilities and reasons, local changes, actual validation, artifacts/instructions, and external or unverified work. For a runtime target, report actual health/rollback status; otherwise use local-delivery acceptance.

49
internal/skills/builtin/fd-engineering/references/execute.md Normal file
View File

@@ -0,0 +1,49 @@
# Execute
For /FD-execute and explicit implementation requests. Loading this reference does not approve implementation.
## Start or resume
- Confirm the goal, acceptance, effective plan/version (or eligible quick-path request), and actual approval. Reuse a complete user-supplied plan explicitly requested for implementation.
- /FD-execute directed at the single clear unblocked current plan can approve it. An explicit small local request meeting [workflow.md](workflow.md)'s quick-path criteria can provide its own short plan/approval. Otherwise use [plan.md](plan.md) to establish a suitable plan and resolve blockers; do not start unapproved edits.
- For complex work read [task-record.md](task-record.md) and [todo.md](todo.md). Reconcile files, completed IDs, evidence, recent revisions, and the current/next step.
- Protect user and unrelated task edits. Investigate discrepancies before trusting recorded completion; do not overwrite, clean, or mix unrelated changes.
- Reuse valid approval across turns and real capability limitations. Report a missing necessary write/execution capability without requesting an IDE mode, waiting for a button, or reapproving the same plan.
## Protocol progress
The effective protocol plan and hierarchical TODO guide implementation. Update real leaf states, affected parents, the current step, evidence, and next action after meaningful work units. Failed, blocked, unrun, or pending-verification items are not completed. A code change alone may leave its item 待验证.
Do not require or maintain a parallel host plan/task board. If an old host artifact is the only plan, reconcile its verifiable effective content and approval into the single protocol record before relying on it. If later edits invalidate previous results, retain historical evidence and mark the affected work 待验证.
## Implement continuously
Follow dependency order in small reviewable changes. Choose in-scope details independently. Validate a reasonable work unit and continue without per-item success questions.
Reuse verified capabilities and real APIs/configuration. Use tools suitable for the environment and reviewability. Avoid unrelated refactors or formatting.
Handle relevant inputs, state, failure, and resource boundaries. Integrate the agreed smallest user path early, checking actual results across its necessary layers. Preserve the affected existing behavior and compatibility promised by the plan. For UI changes follow the product-copy boundary in [uiux.md](uiux.md), retain real labels/status/errors, and implement the approved action states and recovery instead of compensating with explanatory notes.
For a defect, connect the observed symptom and supported cause to the specific fix, then repeat the same triggering case and relevant nearby normal cases. Capture pre-fix failure when feasible; if it cannot be reproduced, explain the evidence and remaining uncertainty instead of claiming a confirmed root cause. An exception disappearing is insufficient when the reported defect concerns lost data or wrong results. Add a meaningful regression check where appropriate, not tests mechanically for low-impact wording or record edits.
## Run and interpret checks
Before editing, establish a relevant baseline when existing checks can run at proportionate cost. Preserve results from before and after, distinguishing pre-existing failures, new failures, and resolved failures. Do not fix unrelated baseline problems without appropriate scope; an unavailable baseline remains a limitation.
Prefer declared project test, type, static-analysis, build, and manual-acceptance entry points. Test observable behavior through stable interfaces and meaningful state/output; interaction assertions are useful only where the interaction is itself a requirement. For example, persistence checks should read the saved result rather than only assert that a save method was called. Run focused checks and applicable required checks. Repeat or broaden only for new changes, failures, or unresolved concerns.
Record real commands, result summaries, and unverified scope. Mocks prove only covered behavior, not real integration or deployment. Investigate and fix failures within scope; never weaken valid assertions to pass.
Check authorization before diagnostics that contact real services, modify databases, or trigger publication. Without Git, use file comparison, builds, and observable behavior.
## Deviations and blockers
Report routine adjustments. Before substantive requirement, public-interface, selected-dependency, or scope changes, preserve state, explain reason/impact, record the revision and affected IDs, and confirm affected parts. Do not rewrite history to hide deviation or cancel failed checks to make completion appear.
Report partial completion or blockers honestly, with evidence, attempted approaches, and needed conditions. Stop repeated attempts that add no information. Continue independent authorized work where useful.
## Self-review and deliver
Compare goals, the effective plan, final changes, and actual checks. Inspect unmet acceptance, unrelated edits, duplication, needless abstraction, fake APIs, placeholders, and silent fallbacks. Fix in-scope issues and validate.
Update the task record and required parent acceptance, then report changes, rationale, actual checks/results, remaining IDs, gaps, and risks in Chinese. Claim completion only when acceptance and relevant checks support it. For distributed packages or executables apply [devops.md](devops.md)'s actual-artifact smoke checks where relevant. Git and external actions retain their separate explicit-authorization requirements.

54
internal/skills/builtin/fd-engineering/references/grill.md Normal file
View File

@@ -0,0 +1,54 @@
# Grill: interrogate decisions
For /FD-grill or consequential uncertainty found during research/planning. Apply core rules. Use it to clarify needs or challenge an existing proposal.
## Establish boundaries
Read the idea, relevant code, task record, and settled decisions. Reuse project terminology; clarify ambiguity only when it affects a decision.
Sketch major decisions and dependencies. Resolve upstream choices first. Match depth to the problem; do not impose a question quota or import unrelated engineering concerns.
## Decision coverage and pacing
Track which consequential choices are verified facts, user-confirmed, explicitly delegated, open, or conditionally deferred. Repository evidence can establish facts, not silently choose user preferences. A broad answer or accepting one option does not delegate all remaining choices.
Before concluding, check that upstream goals, scope, observable acceptance, and consequential tradeoffs have an actual basis. For UI/UX, follow its fuller decision checklist and external-research gate. Do not invent a question quota, but do not treat a sparse exchange as agreement while decision categories remain open.
## One consequential question per round
1. Investigate relevant implementations, configuration, types, and documentation before asking about discoverable facts.
2. For consequential technical uncertainty unresolved locally, consult version-relevant official sources or comparable engineering examples. Explain applicability; user preferences do not require external proof.
3. Ask one consequential Chinese question in conversation, with meaningful choices when useful, a recommendation, and its cost; then wait for the answer. No particular question-card tool is required. Do not batch unresolved decisions or treat silence/default choices as an answer.
4. A recommendation may be a small experiment before deciding. State missing evidence instead of forcing certainty.
5. Update the decision and downstream impact from the answer. Use concrete scenarios to clarify material ambiguity; do not repeat already sufficient answers.
6. Keep each round short: at most a few brief context/rationale bullets before the question. Do not produce the full brief, plan, prototype, or a long decision essay until consequential choices are resolved. Provide a compact snapshot only when useful or requested.
Use a concise Chinese question structure when useful:
~~~text
正在决定什么：
已知依据与仍不确定的部分：
推荐选择及理由：
需要接受的代价：
本轮问题：
~~~
If the user delegates a choice, make a reasonable decision within authorization and record its rationale and cost. Acceptance of a recommendation settles that choice, not implementation approval.
## Test plausible failure
Choose scenarios relevant to the actual decision: partial failure, input boundaries, retries, data corruption, permissions, resources, or unavailable dependencies. Do not invent distributed scale, multi-tenancy, or cloud requirements for a local tool.
Before concluding a complex proposal, examine a credible failure after implementation, the most damaging mistaken assumption, observable warning signals, and a preventive check, mitigation, or rollback.
Analyze risks answered by evidence yourself. If user judgment is needed, keep asking one question per round rather than batching the failure analysis.
## Record and conclude
Record consequential questions, choices, reasons, evidence, accepted tradeoffs, unverified assumptions, and downstream effects. Distinguish open, decided, and conditionally deferred items; accepted risk is separate from whether a decision is settled.
Defer nonblocking items only with a reason they do not invalidate current work and a trigger to revisit. The user may pause and receive partial conclusions; label blockers clearly.
Conclude in Chinese when critical decisions are clear and remaining items do not invalidate implementation. Reuse effective decisions. For complex work use the same file in [task-record.md](task-record.md), rather than parallel decision logs or unsolicited global terminology edits.
If a conclusion changes an approved plan, record the affected revision and seek its confirmation before implementing it.

33
internal/skills/builtin/fd-engineering/references/plan.md Normal file
View File

@@ -0,0 +1,33 @@
# Plan: executable protocol specification
For /FD-plan and substantive revisions. Apply core scope/approval rules and [workflow.md](workflow.md). Planning may maintain records when permitted; business code, dependencies, and engineering configuration remain unchanged.
## Establish decisions and evidence
Use research, an existing task, requirements, or a new goal. Investigate relevant files, symbols, dependencies, configuration, and current behavior; reuse established decisions.
Use [grill.md](grill.md) for unresolved consequential choices, one Chinese question per round. Preferences and tradeoffs stay open until confirmed or explicitly delegated. A plan with blocking unknowns is a draft, not approved work.
Compare real alternatives only when a tradeoff exists. Prefer reuse and direct solutions; justify new dependencies, replacements, and abstractions against present needs.
## Construct and self-review
Include applicable goals/scope/observable acceptance, chosen approach and reasons, module responsibilities and data flow, changed contracts/configuration/dependencies, ordered steps, validation and failure scenarios, compatibility risks, and necessary rollback. Specify actual interfaces only when relevant and verified. Match depth to task size.
For a new feature, prioritize the smallest meaningful user path through the actual required layers before expanding variants: input → action → observable result, including persistence/reopen when relevant. For local changes identify their real entry and outcome; do not invent a full application or infrastructure. Order TODOs around usable outcomes rather than postponing all integration until components are complete. Prototype mock behavior remains separate from production integration evidence.
State the existing affected behaviors that must remain: relevant callers/public contracts, saved files/configuration, defaults, and output formats. Where a change affects persistent data, identify compatibility/migration, representative old data, restoration needs, and whether data effects are reversible; reverting code does not itself restore changed data. Use staged compatibility only when actual consumers or risk justify it.
If a consequential technical assumption could invalidate this plan, settle it using the bounded experiment in [research.md](research.md), or keep the plan conditional/draft with explicit impact. For UI work carry the approved copy boundary and key action/state/recovery expectations from [uiux.md](uiux.md) into implementation acceptance, including the ban on unrequested annotations.
Convert implementation into [hierarchical TODO](todo.md): stable IDs, suitable nesting, leaf actions/results/checks, dependencies, and meaningful parent acceptance. Include necessary verification and self-review, not only coding. Pending approval is not an in-progress implementation item.
Self-review completeness, real references, dependencies, unsupported premises, responsibilities, complexity, error handling, and checks. A planning self-review is not evidence that implementation tests passed.
## Save, present, and approve
For complex work, put the effective protocol plan and TODO in the same [task record](task-record.md) with version and approval status. Do not create a second authoritative plan or require an IDE plan artifact. Short work may present its complete concise plan in conversation. If record writes are unavailable, retain the full usable plan in conversation, mark persistence pending, and continue permitted planning.
Present the Chinese plan or its real file reference plus the decisions needed for review, blockers, risks, and approval status. Do not hide critical content behind a file that was not created. Await implementation approval; reuse an explicit implementation request for the same complete plan rather than asking again.
After approval, continue under [execute.md](execute.md). Preserve the approved content and substantive replacement history. When importing an older host-created plan, retain its original reference and approval provenance, copy only verifiable effective content into this protocol record, and disclose unavailable content or unclear approval instead of inventing it.

31
internal/skills/builtin/fd-engineering/references/research.md Normal file
View File

@@ -0,0 +1,31 @@
# Research
For /FD-research or targeted investigation in another stage. Apply the core scope, language, authorization, and protocol workflow rules.
## Locate the task
Accept an idea, symptom, requirement, file reference, or existing task. If no goal can be inferred, ask which problem to investigate. Search relevant entry points instead of reading the entire project.
## Investigate
1. Read relevant task records, documents, and conventions. Trace entry points, calls, data flow, dependencies, and constraints.
2. Search for reusable modules, standard-library capabilities, installed dependencies, and suitable established solutions.
3. For defects, record the expected/actual behavior, trigger, and a reproducible case when feasible. Separate observed symptoms from candidate causes; use relevant logs/call paths to support or disprove the cause, and retain uncertainty when reproduction or evidence is unavailable. Existing diagnostics may run if they do not edit business code/configuration; check authorization before real-service or data-changing operations.
4. Separate facts, inference, preferences, assumptions, and unknowns. Attach file/symbol locations, real command results, or sources.
5. Check whether goals, scope, acceptance behavior, and consequential tradeoffs are clear. Investigate facts yourself; use [grill.md](grill.md) for unresolved intent or choices.
## Resolve a potentially invalidating assumption
When an uncertain API, platform capability, file format, or packaging constraint could invalidate the approach, propose or perform a bounded isolated experiment within existing authorization. State the one question, representative input/environment, observable success/failure, and stopping condition. Use available resources or an explicitly approved disposable environment; do not change business code, project dependencies/configuration, user data, or real services to investigate. Seek approval for scope/capability expansion.
Record what the experiment actually establishes and its limits. Experimental code is not automatically production code, a new dependency choice, or proof for other environments. Do not require an experiment for ordinary settled work.
Recommendations and tradeoffs are allowed to help the user decide; they are not implementation approval.
## Output and stop
In Chinese, summarize current behavior and evidence, goals/scope, reuse, observable acceptance scenarios, decisions, and remaining unknowns with impact.
Stop when the facts needed for planning are supported and intent is sufficiently clear. Preserve unknowns and propose validation instead of inventing business rules.
For complex work follow [task-record.md](task-record.md). Maintain records only when permissions allow; otherwise retain conclusions in the conversation. End with the next planning step rather than automatically implementing. When findings point to a definite next stage (interface design, planning, implementation, review), name the matching FD command in the closing suggestion; if the user agrees in this same session, continue by that stage reference directly — including its protocol stage and approval rules — instead of requiring manual command input.

32
internal/skills/builtin/fd-engineering/references/review.md Normal file
View File

@@ -0,0 +1,32 @@
# Review
For /FD-review. Apply core rules and the REVIEW protocol stage. Use actual inspection tools; reviewed code/configuration remains read-only by default. Track a complex review using [todo.md](todo.md) without treating findings as approved fixes.
## Select evidence
Accept selected changes, files, behavior, implementation/plan comparison, or a bounded existing-code audit. Read requirements, the effective plan, and task record. A missing plan does not prevent review; do not invent a baseline.
With Git, inspect relevant diffs, context, and callers. Without Git, inspect specified files, available comparisons, or reproducible behavior. Ask about ambiguous targets instead of scanning the entire project.
## Review applicable concerns
- Requirements: acceptance, omissions, and unrelated changes.
- Correctness/regression: triggers, boundaries, state transitions, failure handling, and caller impact.
- Evidence: real APIs/configuration/dependencies, pre-existing versus new failures, behavior-based assertions, and whether the original defect was actually retested.
- Maintenance: reuse, necessary abstractions, and correct responsibilities.
- Relevant risks: data, permissions, resources, affected old callers/configurations/files, migration/restoration, or release impact as applicable.
- User path: the requested observable result works across necessary layers; mocks or generated parts do not prove integration.
- UI: approved action states and recovery, the product-copy boundary from [uiux.md](uiux.md), unrequested adjacent commentary, and accidental removal of actual labels/status/errors.
- Delivered artifact: where packaging is in scope, distinguish a built file from the package actually started and exercised.
Judge plan differences by their actual impact, not wording alone. Investigate real trigger paths and constraints that could disprove each suspicion.
Run targeted tests, builds, or static checks when appropriate. Checks may produce caches, build artifacts, and reports, not rewrite source, snapshots, configuration, or real data. Avoid formatters, update modes, migrations, and publication. Existing task records may receive review findings when permissions allow.
## Output and stop
In Chinese, report actionable issues with location, evidence, trigger, actual impact, priority, and a necessary fix direction. Distinguish confirmed defects, accepted tradeoffs, and unverified hypotheses.
Order by impact; do not dilute issues with stylistic preferences. If none are found, state scope, checks, and limitations without claiming defect-free code.
Finish the agreed review. Fix only after an explicit request and applicable plan/authorization; this command alone does not authorize fixes, staging, or commits.

58
internal/skills/builtin/fd-engineering/references/task-record.md Normal file
View File

@@ -0,0 +1,58 @@
# One task record
Use one record for multi-step, multi-stage, or long-running work; short changes can use a brief plan and conversation. Read on creation/resumption, not every turn.
## Location and authority
Reuse the project's task-document convention. Otherwise use .tasks/<task-slug>.md under the project root. Avoid collisions and overwrites; ask about ambiguous task identity rather than selecting by modification time.
The effective protocol plan/version and hierarchical TODO in this record are the implementation specification and progress source. Keep goals, decisions, authorization, and evidence together. Do not create parallel full plans, decision logs, terminology files, or reports without a project convention or user need.
## Minimal structure
Write user-facing records in Chinese. Include only relevant sections; omit inapplicable fields. System usernames, Git branches, and per-step timestamps are not required.
~~~markdown
# 任务名称
## 当前状态
- 协议阶段与子阶段：
- 有效计划版本与批准状态：
- 批准依据及授权范围：
- 当前 TODO 编号：
- 阻塞、恢复条件与下一步：
## 目标、范围与验收
## 研究依据与未验证假设
## 决策与取舍
## 有效计划与分层 TODO
## 验证证据
## 修订与偏差记录
## 剩余风险与交付结论
~~~
Use [todo.md](todo.md) for task IDs, nesting, states, verification, and parent completion. Give consequential decisions stable IDs when useful. Record question, choice, evidence, reason, accepted cost, and downstream effects. Deferred nonblockers need a revisit trigger; accepted risk is separate from settlement.
For UI/UX, keep the brief and approval, reference-research authorization, explicit candidate count, artifact scope, direction differences, selection, refinements, and rendering/interaction evidence here. Keep prototype approval separate from production approval. Record preview command, directory, port/URL, actual session/PID and ownership evidence, then verified cleanup.
## Update, revision, and migration
- Update current status, progress, factual corrections, and open items for readability.
- Record actual approved version/content and authorization; never invent or expand it on resumption.
- Preserve approved original decisions or sufficient exact content to reconstruct them. Append substantive revisions with affected IDs, original/replacement, reason, impact, supersession, and approval.
- A revision does not inherit approval automatically; reconfirm affected parts, retaining unaffected decisions.
- Record real commands, results, and scope. When applicable include baseline/after comparison, defect trigger and causal evidence, user-path results, protected behavior, bounded-experiment limits, and actual-artifact checks. Reuse existing sections rather than adding mandatory parallel reports. Preserve old results but mark affected TODOs 待验证 when later edits invalidate them.
- Research, Grill, planning, and review may maintain records when permitted, not business code/configuration. If writing is unavailable, retain Chinese conclusions in conversation, mark persistence pending, and sync when allowed; do not request a host mode merely to save notes.
- Import an existing host plan by retaining its original reference and approval history and reconciling verifiable effective content into this record. Do not keep two competing authoritative plans. Missing content or unclear approval remains an explicit gap; require no host tool merely to migrate.
## Resume and close
Read stage/sub-stage, effective version, approval, current/remaining IDs, evidence, and recent revisions. Reconcile actual files, dependencies, check freshness, and any recorded preview handles. Investigate discrepancies, protect unrelated changes, and establish the next action before continuing.
Close against acceptance with complete, partial, or blocked status and actual evidence. Keep failed/unrun checks, cleanup gaps, and remaining IDs visible. A final response is not evidence that the work is complete.

58
internal/skills/builtin/fd-engineering/references/todo.md Normal file
View File

@@ -0,0 +1,58 @@
# Hierarchical TODO protocol
Use for planning, multi-step work, and resumption. The effective protocol plan and its TODO are authoritative; no host task board or plan generator is required. Persist complex work in the single record described in [task-record.md](task-record.md). A short task can keep its plan and steps in conversation.
## Structure and identifiers
Group work by outcome or work package, then subtasks and independently verifiable actions as useful. Do not force three levels or split every edit into a new item. Each executable leaf needs an action, expected result, and verification method; note dependencies when order alone is insufficient. Parent items state the outcome and any additional acceptance condition. For new features prefer a first parent representing the smallest usable user path through the required layers, with build/integration/validation children, then expand variants. A component milestone alone is not proof that the user path works.
Use stable identifiers such as 1, 1.1, and 1.1.1 for dependencies, checks, and revisions. Add a new unused child/sibling ID rather than renumbering existing references. A materially changed or superseded item retains its history and replacement mapping; adding detail is not permission to expand scope. Keep the current item and next action identifiable.
## States and completion
Write task records and status labels in Chinese. Only 完成 uses a checked box.
| State | Meaning |
|---|---|
| 待办 | Not started; dependencies or approval may still be pending |
| 进行中 | Work is actively underway |
| 待验证 | Work produced a result, but its required checks are incomplete or stale |
| 完成 | Expected result and applicable acceptance/checks are supported by actual evidence |
| 失败 | An attempted action or check failed; retain result and next diagnostic/fix |
| 受阻 | A required condition/capability is missing; record it and the resume trigger |
| 取消 | Deliberately removed or superseded with reason and acceptance impact recorded |
A parent is complete only when every still-required child is complete and its own acceptance is met. Failed, blocked, unrun, or pending-verification children cannot count as complete. Do not calculate completion merely from box counts. Summarize the actual limiting child in the parent status; a mixed subtree need not share one state.
Cancellation is unchecked and is not success. If it removes approved scope or a required acceptance/check, record and obtain approval of the affected revision before treating that child as no longer required. Never drop checks, cancel failed work, or change history to manufacture completion.
## Progress and evidence
After a meaningful work unit, record real changes/checks and update the related leaf, affected parents, current pointer, and next action. Keep updates concise; no per-edit timestamps or repeated full checklists are required. After approval, continue through available dependencies and checks without asking whether every step succeeded.
Reference actual commands/results or artifact evidence from verification entries. Code generation alone is not verified behavior. A failed check stays failed until a meaningful fix and successful rerun; unavailable checks remain unverified with impact, not completed. Required manual acceptance remains pending unless the effective plan legitimately changes.
If later edits invalidate a prior check, retain the old evidence and mark affected items 待验证 until rerun. On resumption reconcile files, dependencies, approval, recent revisions, and evidence before trusting completed boxes. Do not mark unknown prior work complete or blindly restart all finished work.
## Example record
This illustrates a mixed incomplete subtree, not actual executed work.
~~~markdown
- [ ] 1 缓存修复与验收 — 进行中；验收：离线可读且写入失败不丢失旧值
- [x] 1.1 核对现有读写路径 — 完成；证据：研究 R1 的文件与调用链
- [ ] 1.2 修复原子写入 — 待验证
- 行动：沿用现有文件替换能力修改写入路径
- 预期：写入失败仍可读取旧值；依赖：1.1
- 验证：运行对应回归用例；当前证据：V1 仅记录改动，检查尚未运行
- [ ] 1.3 验证目标环境 — 受阻；依赖：1.2；缺少测试设备，到位后恢复
当前步骤：1.2
下一步：运行约定回归；不能因 1.1 完成就勾选父任务 1
~~~
## Revisions and closure
Routine in-scope implementation details need no new approval. Preserve the approved plan and append substantive revisions, affected IDs, reason, impact, replacement, and approval; use [workflow.md](workflow.md) for the boundary.
Close against acceptance as complete, partial, or blocked with evidence and remaining IDs. Review findings and UI/UX preview cleanup can be TODO items when relevant; opening a file, generating a plan, or reaching the final response does not itself close the task.

112
internal/skills/builtin/fd-engineering/references/uiux.md Normal file
View File

@@ -0,0 +1,112 @@
# UI/UX: brief, web options, and design handoff
For /FD-uiux and interface-design proposals. Apply core language, scope, evidence, and protocol workflow rules. The deliverable is an approved design expressed through web prototypes, not production implementation. Record UIUX sub-stage as discovery, brief confirmation, prototype generation, selection, refinement, or handoff. Use [todo.md](todo.md) for substantial artifact work, checks, and cleanup, within the same task record.
## 1. Ground the task
Read relevant product/task documents, existing interfaces or captures, design rules, components, tokens, and assets. Identify the actual output project separately from reference projects. Work with empty projects, reference collections, and existing applications without assuming all are greenfield.
Identify the target platform, audience, primary tasks, and whether the request is new design, refinement, or redesign. Preserve existing identity and behavior for refinement; clarify replacement scope before redesign. Missing design documentation alone does not authorize replacing an existing visual system.
Use [grill.md](grill.md) for consequential unknowns, one question per round, with evidence, a recommendation, and cost. Investigate discoverable facts yourself and reuse effective decisions.
## Decision coverage before proposing
Check these categories: purpose/audience and priorities; platform/viewports/input; primary flow and information/navigation organization; tone and visual constraints; density/layout direction and meaningful copy/states; existing components/reuse constraints; reference permission; explicit candidate count and output scope.
For each consequential choice, keep evidence and status: confirmed, explicitly delegated, verified fact, open, or deliberately deferred. Confirm or obtain scoped delegation for preference-driven choices; do not turn a guess, a generic adjective, or one broad answer into approval of the rest. Low-level spacing details can follow the confirmed direction.
Ask one Chinese question per round in conversation, starting upstream. Keep the context to a few short bullets and wait for the answer. Do not dump a full brief, many decisions, or prototypes while categories remain open. Present the consolidated brief only after blockers are resolved. Reuse explicit existing decisions rather than adding a fixed question quota.
## 2. References require the appropriate scope
Inspect user-supplied references within their stated scope. If none are supplied, ask whether external visual/competitor research is wanted, unless the user already decided this for the task. Wait for affirmative authorization before such research; asking without an answer is not approval.
If declined, continue from local material and confirmed constraints. Record unknown competitors or reference gaps without inventing research. Do not silently expand supplied references into new competitor/style searches. Apply this gate when using Grill or other design guidance too.
Separate observed reference facts, design inference, and unverified assumptions. Extract applicable principles rather than copying an entire site or template. Prefer existing/local assets and system fonts; additional remote resources or dependencies must be justified in the brief and respect the research decision.
## 3. Confirm the brief and candidate count
Do not silently default to any number of candidates. Ask the user when the count is unspecified; recommend a number with its effort and comparison cost. Reuse an explicit count. Additional directions require a new explicit count, not automatic expansion; refining the selected direction does not reopen that question.
Present a short Chinese brief covering applicable decisions:
- Product purpose, audience, primary task, and observable design goals.
- Target platform, primary viewport(s), input conventions, and product-copy language.
- New/refine/redesign scope, tone, existing identity, components, and assets.
- Supplied references, external-research decision, evidence gaps, and assumptions.
- User-chosen count and meaningful differences to explore.
- Key pages, operable controls and important action/state/recovery mappings, approved product copy and annotation restrictions, layout scales, output location, and reuse/dependency choices.
Request brief confirmation before creating prototypes. A previously explicit approval of the same complete brief is reusable. Resolve blockers first; update and reconfirm materially changed goals or scope, not every spacing adjustment.
## 4. Make design choices accountable
- Avoid gradients, rounded corners, and glow as default styling. Use them only when the confirmed brief explicitly requires or justifies them. Respect a confirmed existing identity rather than imposing a new universal style.
- Tie choices to the product's content, audience, task, and setting. For multiple candidates, vary layout, information organization, interaction organization, or visual expression meaningfully; palette-only reskins do not qualify.
- Give each direction a clear rationale and tradeoff. Avoid generic style labels as substitutes for design decisions. Instructions cannot change the model's decoding mechanism or guarantee originality.
- Apply the product-copy boundary below. Preserve factual content; use realistic, identified fixtures when real content is unavailable, without fabricated endorsements or metrics. Keep fixture explanations outside the product canvas.
- Define coherent alignment, spacing, type hierarchy, control sizes, density, and grouping for the target platform. A rough coverage prototype still needs deliberate layout details.
- Evaluate existing components, native semantics, and necessary dependencies before custom controls. Do not let a component kit dictate the composition or rebuild mature behavior merely to escape a template. New frameworks, full UI kits, or templates require necessity and cost in the confirmed brief.
## Product-copy boundary
Do not add explanatory annotations beside, beneath, or around controls, cards, charts, or other product elements. This concerns visible interface text, not source-code comments. Do not spontaneously explain a control's purpose, teach its operation, justify the design, describe implementation/mock behavior, or add generic summary/helper lines. Perceived usefulness alone is not permission.
Keep real product content: button/field names, units, actual values, actual loading/success states, and genuine validation/error feedback in the appropriate state. For example, 项目名称, 元, 已保存, and 名称不能为空 are allowed; an unrequested line 给项目起一个容易识别的名字，方便以后查找 is not.
Additional explanatory help copy requires the user's explicit request or confirmation of that concrete wording/purpose; a broad brief approval is not blanket approval for invented notes. Do not evade the rule by moving the same commentary into tooltips, info icons, placeholders, or page corners. Preserve established/user-provided product content within the agreed refinement scope rather than silently deleting it.
Put design/implementation explanations in conversation or the handoff record. Keep selection rationale in a dedicated gallery comparison area outside the product canvas, never attached to product controls. Enforce this boundary during prototype refinement and carry it into production planning, execution, and review.
## Key actions, states, and recovery
For each important operation specify the user's trigger, observable result, and how to continue on failure. Include applicable waiting/success/error, repeated submission, retry/cancel, retained input, and unsaved-change behavior; do not force irrelevant states onto every button. Resolve consequential behavior choices through Grill, and keep the agreed mapping in the same brief/task record.
For saving, clarify whether duplicate submission is blocked, when success appears, whether input survives failure, and how retry/leaving works. Prototype states are simulated and cannot prove real persistence; production acceptance must exercise the actual path. Do not compensate for undefined behavior by adding explanatory notes.
## 5. Generate isolated web prototypes
After the complete brief and explicit candidate count are approved, enter the prototype-generation sub-stage and verify actual write/preview capabilities under the host's permissions. Approval covers only the agreed prototype artifacts and related checks. It does not approve business-code, project-dependency/configuration changes, real business actions, publication, or deployment.
Follow existing prototype conventions. Otherwise use prototypes/uiux/<task-slug>/ under the target project. Provide exactly one index.html selection interface with tabs, radio buttons, or a selector that switches candidates inside the same page/viewport. Candidate files can be separate internally, but do not open one window/tab or start one server per candidate. Keep selection controls, rationale, fixture/validation notes, and limitations outside the product canvas. Avoid collisions and unrelated overwrites.
Default to lightweight HTML/CSS/JavaScript. Reuse suitable assets, tokens, or components when they work inside the isolated artifact without production changes. Do not introduce a new application framework or build pipeline just for a preview.
Implement the agreed key controls, such as tabs, expansion, dialogs, toggles, and form feedback, with a small set of local simulated states. Actions must produce the described prototype behavior, not decorative buttons or generic click alerts. Do not connect real services or imply that mocked state proves working business integration.
The browser is a cross-platform design medium, not a decision to replace the production stack. Follow the target platform's density, navigation, and input expectations; state which native behaviors the HTML cannot validate.
## Preview ownership and cleanup
Prefer a directly openable local page when the available browser supports it. If a server is necessary, use one task-owned preview session for the entire gallery. Before launch record the intended command, directory, and port; immediately after launch record the actual returned session/PID, URL, and ownership evidence. Never guess a PID. Reuse a suitable existing user-owned server only without taking ownership; never terminate it or the user's browser application.
When the user explicitly selects a candidate, record the selection, then immediately close the task-created selection tabs and stop every task-started preview server/watcher/child process using its actual handle or verified PID. Verify exit; do not merely print that cleanup happened. Never kill all node/python/browser processes or terminate a process by port/name without proving ownership.
While awaiting selection, the gallery workflow is still active: keep at most one necessary owned preview session and retain its handle. Ending a chat turn while waiting is not final workflow completion. On resumption, reuse and verify the recorded session rather than launching duplicates.
Refine the selected files after closing the selection session. If a further render is needed, open only the selected direction in one temporary task-owned session, then close/stop it before handoff. Apply the same owned-session cleanup on cancellation, failure, or final completion. Preserve artifact files. On resumption, inspect recorded handles before starting duplicates. Report any cleanup failure and remaining owned handles honestly.
## 6. Inspect, select, and refine
When tools permit, open and render each candidate at the agreed viewport(s). Inspect actual alignment, dimensions, spacing, overflow/clipping, content length, focus, important feedback, and the agreed operable controls/states. Fix what one inspection reveals before repeatedly capturing again. Report only checks actually performed.
Present a concise Chinese comparison, costs/limits, and the single switchable gallery entry. Ask for selection in conversation and wait for the user's explicit choice; do not infer it from a default or silently pick a favorite. Run the cleanup transition above as soon as selection is received.
Refine the selected direction's layout details, approved product copy, and key states. Check for unrequested adjacent commentary while preserving real names, units, states, and error feedback. Preserve the selected concept and brief unless the user changes them; record substantive revisions and confirm the affected scope. Do not polish all rejected directions or generate extras without request.
If rendering or interaction tools are unavailable, retain manually openable artifacts and distinguish generated files from unverified visuals and interactions. Ask for user review where necessary; never claim to have seen or tested them. A render cannot prove user research or all native-platform behavior.
## 7. Handoff and resume
Use the same record described in [task-record.md](task-record.md) for the brief, research authorization, candidate count, differences, selection, revisions, artifact locations, real tool/check results, preview process ownership/cleanup, and actual validation. Do not create parallel global design documents by default.
Deliver in Chinese: the selected/refined prototype, user flow, key action/state/recovery mappings, approved copy and annotation restrictions, visual/layout rules, justified exceptions, reuse guidance, remaining assumptions/limits, and implementation acceptance points. The user can reference this in /FD-plan, then approve production implementation for /FD-execute. Do not automatically perform that implementation.
## Guidance provenance
The visible-annotation prohibition, fixed protocol markers, and production handoff restrictions are FD user requirements, not claims that the source design skills prescribe these exact rules.
Distilled from frontend-design (intentional visual direction and useful copy), impeccable (brief priority, refinement/redesign boundaries, rendered craft checks), and ui-ux-pro-max (platform-aware UX, states, layout, and component guidance). Their installation, scripts, and databases are not runtime requirements. Load only relevant optional guidance and preserve FD scope and research gates.

48
internal/skills/builtin/fd-engineering/references/workflow.md Normal file
View File

@@ -0,0 +1,48 @@
# Protocol stages and authorization
Use on entry, stage changes, approval changes, and resumption. FD stages are responsibilities managed by this skill; they do not request or activate a host application's modes.
## Select and advance
Use the explicit FD command or natural-language intent and the single clear current task. Otherwise infer the stage from the effective task state; use research when facts or goals are still unclear. Do not require every stage, exact switching phrases, or a fixed report. Use the exact marker below once as the first line of each substantive reply or question body, followed by one blank line before the body so Markdown renderers preserve the line break; do not repeat it in progress-only messages. It describes the FD protocol, never a host-mode transition.
| Command / stage | Required body-first marker | Work and boundary |
|---|---|---|
| /FD-research / RESEARCH | [FD:已进入研究模式] | Investigate evidence and reuse; clarify intent; no business or engineering edits |
| /FD-grill / GRILL | [FD:已进入质询模式] | Resolve consequential decisions one question per round; conclusions do not approve implementation |
| /FD-plan / PLAN | [FD:已进入计划模式] | Produce a reviewable protocol plan and hierarchical TODO; await implementation approval |
| /FD-uiux / UIUX | [FD:已进入界面设计模式] | Discover → confirm brief → generate prototypes → select → refine → hand off; confirmed brief/count authorize isolated artifacts only |
| /FD-execute / EXECUTE | [FD:已进入执行模式] | Reconcile an approved plan or eligible explicit quick-path request; implement, validate, and self-review continuously |
| /FD-review / REVIEW | [FD:已进入审查模式] | Review actual implementation; no automatic source fixes or Git actions |
| /FD-devops / DEVOPS | [FD:已进入工程交付模式] | Investigate and plan first; implement applicable capabilities when authorized |
| /FD-commit / COMMIT | [FD:已进入提交说明模式] | Inspect actual changes and draft a message; no automatic index or repository mutations |
Choose the marker for the work actually underway: an execute request lacking a usable approved plan uses PLAN first, unless it qualifies for the quick path. Merely loading an auxiliary reference does not change the marker; actually entering a separate Grill conversation uses GRILL, then returns to the calling stage when settled. Execution self-review remains EXECUTE. UIUX sub-stages can be stated briefly after its marker without inventing new marker formats. Never prefix raw deliverable contents with the marker.
A stage may load another reference for necessary investigation or Grill without expanding authorization. At handoff, name the relevant next FD command when useful. If the user agrees, continue by its reference; do not require typing a command or simulating a slash-menu invocation.
## Approval and revision
Record the effective plan version/content and the actual approval basis. An explicit request to implement a complete user-supplied plan, agreement to a clearly identified plan, or /FD-execute directed at the single clear unblocked current plan can approve that plan. Reuse valid approvals across turns and recovery; do not wait for an IDE button, card, or particular wording.
Accept approval conveyed by the host only when its context actually identifies the user's approval and the relevant plan. The skill does not require or inspect a particular host UI. Missing tools, a stage declaration, silence, a default selection, accepting an observation, or agreeing to one recommendation do not establish approval.
After approval, choose ordinary in-scope details and continue implementation, checks, and self-review without per-step permission questions. Substantive changes to requirements, public interfaces, selected dependencies, or scope need reasons, impact, a recorded revision, and confirmation of affected parts. Unaffected decisions and approval remain reusable. Self-review stays part of execution; a separate requested review uses REVIEW.
UI/UX brief approval covers only the confirmed prototype scope. Selection, design approval, and production implementation approval are separate. Actual commits, pushes, merges, publication, deployment, and other external mutations need explicit intent already present or newly given.
## Explicit small-change quick path
A direct implementation request can itself supply the short plan and authorization when its target, desired result, and verification are clear, the inspected change is small, local, and easily reversible, and no consequential choice remains. State the intended change/check briefly, enter EXECUTE, perform it, verify proportionately, and report. A separate task file or approval round is unnecessary. Examples include changing a specified button label or correcting a known local reference.
Do not use this path for persistent-data/schema/format changes, dependency changes, public-interface changes, security/permission changes, external mutations, broad refactors/redesigns, or unclear scope. Do not infer safety from a small line count. Research, Grill, planning, review, and commit-drafting requests alone do not authorize edits; the UIUX reference/brief/count gates remain intact. If inspection reveals excluded impact, preserve state and establish/confirm the affected plan instead of stretching the quick path.
## Real capabilities and evidence
Use actual available file, search, diff, execution, browser, and process capabilities. Do not discover or request host-specific mode, plan, task-board, or question-card tools as protocol prerequisites. Missing such conveniences is not a workflow blocker; plans, TODOs, and questions are valid protocol artifacts.
Respect the host's actual instructions, permissions, and available capabilities. A protocol transition cannot unlock writes or override read-only restrictions. Keep conclusions in Chinese conversation when persistence is unavailable, mark it pending, and sync when writes are permitted. Preserve approval when a real required capability is blocked; state the affected action rather than asking to approve the same plan again.
Never simulate tool results. Checks require actual results, rendering requires actual inspection, and preview cleanup requires verified closure/exit. If an essential capability is absent, report the real gap and a usable manual artifact or independent next step where possible.
For persistent state use [task-record.md](task-record.md); for steps, completion, failure, and recovery use [todo.md](todo.md).

263
internal/skills/skills.go Normal file
View File

@@ -0,0 +1,263 @@
// Package skills 管理内置 Skill 资源及其向目标项目的安装/移除。
// 状态以文件系统为准：项目 .cursor/skills/<name>/ 存在即已安装。
// skill 目录内的 commands/ 子目录是斜杠命令模板，安装时分发到项目 .cursor/commands/。
package skills
import (
"embed"
"fmt"
"io/fs"
"os"
"path"
"path/filepath"
"sort"
"strings"
)
//go:embed builtin
var builtinFS embed.FS
const (
// builtinRoot 是 embed FS 中内置资源的根目录名。
builtinRoot = "builtin"
// commandsDirName 是 skill 目录内存放命令模板的子目录名。
commandsDirName = "commands"
)
// retiredSkillFiles 记录各内置 skill 更新时需要清理的退役文件。
var retiredSkillFiles = map[string][]string{
"fd-engineering": {
"references/native-tools.md",
"references/mode-switch.md",
},
}
// CommandInfo 描述 skill 附带的一个斜杠命令。
type CommandInfo struct {
Name string `json:"name"`
Description string `json:"description"`
}
// Skill 描述一个内置 Skill。
type Skill struct {
Name string `json:"name"`
Description string `json:"description"`
Commands []CommandInfo `json:"commands"`
}
// skillsDir 返回项目内的 skill 安装目录。
func skillsDir(projectPath string) string {
return filepath.Join(projectPath, ".cursor", "skills")
}
// skillTargetDir 返回某 skill 在项目内的安装目录。
func skillTargetDir(projectPath string, name string) string {
return filepath.Join(skillsDir(projectPath), name)
}
// projectCommandsDir 返回项目内的斜杠命令目录。
func projectCommandsDir(projectPath string) string {
return filepath.Join(projectPath, ".cursor", "commands")
}
// List 返回所有内置 Skill，按名称排序。
func List() []Skill {
dirEntries, err := fs.ReadDir(builtinFS, builtinRoot)
if err != nil {
return []Skill{}
}
result := make([]Skill, 0, len(dirEntries))
for _, dirEntry := range dirEntries {
if !dirEntry.IsDir() {
continue
}
result = append(result, Skill{
Name: dirEntry.Name(),
Description: readFrontmatterDescription(path.Join(builtinRoot, dirEntry.Name(), "SKILL.md")),
Commands: listCommands(dirEntry.Name()),
})
}
return result
}
// listCommands 列出内置 skill 附带的斜杠命令及其 description。
func listCommands(name string) []CommandInfo {
entries, err := fs.ReadDir(builtinFS, path.Join(builtinRoot, name, commandsDirName))
if err != nil {
return []CommandInfo{}
}
result := make([]CommandInfo, 0, len(entries))
for _, entry := range entries {
if entry.IsDir() || !strings.HasSuffix(entry.Name(), ".md") {
continue
}
result = append(result, CommandInfo{
Name: strings.TrimSuffix(entry.Name(), ".md"),
Description: readFrontmatterDescription(path.Join(builtinRoot, name, commandsDirName, entry.Name())),
})
}
sort.Slice(result, func(i, j int) bool { return result[i].Name < result[j].Name })
return result
}
// commandFileNames 返回内置 skill 附带的命令文件名列表。
func commandFileNames(name string) []string {
entries, err := fs.ReadDir(builtinFS, path.Join(builtinRoot, name, commandsDirName))
if err != nil {
return nil
}
names := make([]string, 0, len(entries))
for _, entry := range entries {
if !entry.IsDir() && strings.HasSuffix(entry.Name(), ".md") {
names = append(names, entry.Name())
}
}
return names
}
// Exists 校验内置 skill 是否存在。
func Exists(name string) bool {
name = sanitizeSkillName(name)
if name == "" {
return false
}
info, err := fs.Stat(builtinFS, path.Join(builtinRoot, name, "SKILL.md"))
return err == nil && !info.IsDir()
}
// Install 将内置 skill 同步到项目 .cursor/skills/<name>/，
// 并将其 commands/ 模板分发到项目 .cursor/commands/。
// 目标已存在时同步为最新内置内容，并清理已退役的内置文件。
func Install(projectPath string, name string) error {
name = sanitizeSkillName(name)
if name == "" || !Exists(name) {
return fmt.Errorf("内置 skill 不存在: %s", name)
}
projectPath = strings.TrimSpace(projectPath)
if info, err := os.Stat(projectPath); err != nil || !info.IsDir() {
return fmt.Errorf("项目目录不存在: %s", projectPath)
}
target := skillTargetDir(projectPath, name)
// commands/ 模板单独分发到 .cursor/commands/，不进入 skill 目录。
if err := copyEmbeddedDir(path.Join(builtinRoot, name), target, commandsDirName); err != nil {
return fmt.Errorf("复制 skill 文件失败: %w", err)
}
for _, relativePath := range retiredSkillFiles[name] {
if err := os.Remove(filepath.Join(target, filepath.FromSlash(relativePath))); err != nil && !os.IsNotExist(err) {
return fmt.Errorf("清理退役 skill 文件失败: %w", err)
}
}
if err := installCommands(projectPath, name); err != nil {
return err
}
return nil
}
// installCommands 将 skill 的命令模板复制到项目 .cursor/commands/。
func installCommands(projectPath string, name string) error {
fileNames := commandFileNames(name)
if len(fileNames) == 0 {
return nil
}
commandsDir := projectCommandsDir(projectPath)
if err := os.MkdirAll(commandsDir, 0o755); err != nil {
return fmt.Errorf("创建命令目录失败: %w", err)
}
for _, fileName := range fileNames {
data, err := builtinFS.ReadFile(path.Join(builtinRoot, name, commandsDirName, fileName))
if err != nil {
return fmt.Errorf("读取命令模板失败: %w", err)
}
if err := os.WriteFile(filepath.Join(commandsDir, fileName), data, 0o644); err != nil {
return fmt.Errorf("写入命令文件失败: %w", err)
}
}
return nil
}
// Uninstall 移除项目内的 skill 目录与随附的命令文件。不存在时幂等成功。
func Uninstall(projectPath string, name string) error {
name = sanitizeSkillName(name)
if name == "" {
return fmt.Errorf("skill 名称不能为空")
}
projectPath = strings.TrimSpace(projectPath)
target := skillTargetDir(projectPath, name)
// 防御：只允许删除 .cursor/skills/<name> 一级目录。
if filepath.Base(target) != name || !strings.Contains(filepath.ToSlash(target), "/.cursor/skills/") {
return fmt.Errorf("非法的 skill 路径")
}
if err := os.RemoveAll(target); err != nil {
return fmt.Errorf("移除 skill 失败: %w", err)
}
// 只删除内置清单中的命令文件，不碰用户自建命令。
commandsDir := projectCommandsDir(projectPath)
for _, fileName := range commandFileNames(name) {
if err := os.Remove(filepath.Join(commandsDir, fileName)); err != nil && !os.IsNotExist(err) {
return fmt.Errorf("移除命令文件失败: %w", err)
}
}
return nil
}
// IsInstalled 检测项目内是否已安装该 skill。
func IsInstalled(projectPath string, name string) bool {
name = sanitizeSkillName(name)
if name == "" {
return false
}
_, err := os.Stat(filepath.Join(skillTargetDir(projectPath, name), "SKILL.md"))
return err == nil
}
// readFrontmatterDescription 解析 markdown frontmatter 中的 description。
func readFrontmatterDescription(embedPath string) string {
raw, err := builtinFS.ReadFile(embedPath)
if err != nil {
return ""
}
for _, line := range strings.Split(string(raw), "\n") {
line = strings.TrimSpace(line)
if strings.HasPrefix(line, "description:") {
return strings.TrimSpace(strings.TrimPrefix(line, "description:"))
}
}
return ""
}
// sanitizeSkillName 防止路径穿越：只允许字母数字、连字符、下划线、点。
func sanitizeSkillName(name string) string {
name = strings.TrimSpace(name)
if name == "" || strings.ContainsAny(name, "/\\") || strings.Contains(name, "..") {
return ""
}
return name
}
// copyEmbeddedDir 递归复制 embed FS 子目录到磁盘，skipDir 指定要跳过的子目录名。
func copyEmbeddedDir(embedDir string, targetDir string, skipDir string) error {
return fs.WalkDir(builtinFS, embedDir, func(p string, d fs.DirEntry, err error) error {
if err != nil {
return err
}
if d.IsDir() && skipDir != "" && d.Name() == skipDir && p != embedDir {
return fs.SkipDir
}
rel, err := filepath.Rel(embedDir, p)
if err != nil {
return err
}
target := filepath.Join(targetDir, rel)
if d.IsDir() {
return os.MkdirAll(target, 0o755)
}
data, err := builtinFS.ReadFile(p)
if err != nil {
return err
}
return os.WriteFile(target, data, 0o644)
})
}

154
internal/skills/skills_test.go Normal file
View File

@@ -0,0 +1,154 @@
package skills
import (
"os"
"path/filepath"
"testing"
)
func TestInstallUninstallIdempotent(t *testing.T) {
project := t.TempDir()
if err := Install(project, "fd-engineering"); err != nil {
t.Fatalf("install: %v", err)
}
// 幂等：重复安装不报错。
if err := Install(project, "fd-engineering"); err != nil {
t.Fatalf("reinstall: %v", err)
}
if !IsInstalled(project, "fd-engineering") {
t.Fatal("expected installed after Install")
}
if _, err := os.Stat(filepath.Join(project, ".cursor", "skills", "fd-engineering", "SKILL.md")); err != nil {
t.Fatalf("SKILL.md missing: %v", err)
}
if _, err := os.Stat(filepath.Join(project, ".cursor", "skills", "fd-engineering", "references", "execute.md")); err != nil {
t.Fatalf("references missing: %v", err)
}
// 命令文件应分发到 .cursor/commands/。
commandPath := filepath.Join(project, ".cursor", "commands", "FD-commit.md")
if _, err := os.Stat(commandPath); err != nil {
t.Fatalf("command file missing: %v", err)
}
// 命令模板不应进入 skill 目录。
if _, err := os.Stat(filepath.Join(project, ".cursor", "skills", "fd-engineering", "commands")); !os.IsNotExist(err) {
t.Fatal("commands template must not be copied into skill dir")
}
if err := Uninstall(project, "fd-engineering"); err != nil {
t.Fatalf("uninstall: %v", err)
}
if _, err := os.Stat(commandPath); !os.IsNotExist(err) {
t.Fatalf("command file should be removed: %v", err)
}
if IsInstalled(project, "fd-engineering") {
t.Fatal("expected not installed after Uninstall")
}
}
func TestInstallRefreshesBuiltinAndRetiredFiles(t *testing.T) {
project := t.TempDir()
if err := Install(project, "fd-engineering"); err != nil {
t.Fatalf("install: %v", err)
}
target := filepath.Join(project, ".cursor", "skills", "fd-engineering")
skillPath := filepath.Join(target, "SKILL.md")
if err := os.WriteFile(skillPath, []byte("old skill\n"), 0o644); err != nil {
t.Fatalf("write stale skill: %v", err)
}
workflowPath := filepath.Join(target, "references", "workflow.md")
if err := os.Remove(workflowPath); err != nil {
t.Fatalf("remove workflow: %v", err)
}
for _, name := range []string{"native-tools.md", "mode-switch.md"} {
path := filepath.Join(target, "references", name)
if err := os.WriteFile(path, []byte("retired\n"), 0o644); err != nil {
t.Fatalf("write retired reference: %v", err)
}
}
customPath := filepath.Join(target, "references", "custom.md")
if err := os.WriteFile(customPath, []byte("user-owned\n"), 0o644); err != nil {
t.Fatalf("write custom reference: %v", err)
}
if err := Install(project, "fd-engineering"); err != nil {
t.Fatalf("refresh install: %v", err)
}
got, err := os.ReadFile(skillPath)
if err != nil {
t.Fatalf("read refreshed skill: %v", err)
}
want, err := builtinFS.ReadFile("builtin/fd-engineering/SKILL.md")
if err != nil {
t.Fatalf("read embedded skill: %v", err)
}
if string(got) != string(want) {
t.Fatal("existing skill was not refreshed from builtin content")
}
if _, err := os.Stat(workflowPath); err != nil {
t.Fatalf("missing workflow was not restored: %v", err)
}
for _, name := range []string{"native-tools.md", "mode-switch.md"} {
if _, err := os.Stat(filepath.Join(target, "references", name)); !os.IsNotExist(err) {
t.Fatalf("retired reference %s was not removed", name)
}
}
if _, err := os.Stat(customPath); err != nil {
t.Fatalf("user-owned reference must survive refresh: %v", err)
}
}
func TestUninstallKeepsUserCommands(t *testing.T) {
project := t.TempDir()
if err := Install(project, "fd-engineering"); err != nil {
t.Fatalf("install: %v", err)
}
// 用户自建命令不受影响。
userCommand := filepath.Join(project, ".cursor", "commands", "my-own.md")
if err := os.WriteFile(userCommand, []byte("# own\n"), 0o644); err != nil {
t.Fatalf("write user command: %v", err)
}
if err := Uninstall(project, "fd-engineering"); err != nil {
t.Fatalf("uninstall: %v", err)
}
if _, err := os.Stat(userCommand); err != nil {
t.Fatalf("user command must survive: %v", err)
}
}
func TestInstallRejectsUnknownSkillAndBadProject(t *testing.T) {
if err := Install(t.TempDir(), "not-exist"); err == nil {
t.Fatal("expected error for unknown skill")
}
if err := Install(filepath.Join(t.TempDir(), "missing"), "fd-engineering"); err == nil {
t.Fatal("expected error for missing project dir")
}
// 路径穿越防护。
if err := Install(t.TempDir(), "../evil"); err == nil {
t.Fatal("expected error for path traversal")
}
}
func TestListExposesCommands(t *testing.T) {
list := List()
if len(list) == 0 {
t.Fatal("expected builtin skills")
}
var found *Skill
for i := range list {
if list[i].Name == "fd-engineering" {
found = &list[i]
}
}
if found == nil {
t.Fatal("fd-engineering not listed")
}
if len(found.Commands) == 0 {
t.Fatal("expected commands to be listed")
}
if found.Commands[0].Description == "" {
t.Fatal("expected command description parsed from frontmatter")
}
}