diff --git a/.agents/skills/personal-dev/SKILL.md b/.agents/skills/personal-dev/SKILL.md new file mode 100644 index 00000000..46dbac14 --- /dev/null +++ b/.agents/skills/personal-dev/SKILL.md @@ -0,0 +1,24 @@ +--- +name: personal-dev +description: Use when starting a project, implementing a tracked feature, fixing a bug, or preparing delivery in a project using the personal development system. Not for concept-only questions or unrelated tasks. +--- + +# 个人开发任务入口 + +从工程根目录读取 `AGENTS.md` 和 `docs/agents/project.json`;缺失配置时先列出缺口,只补当前阶段必要事实。遵守宿主与用户指令,本技能不授予外部写操作权限。 + +1. 判断任务与已完成阶段,复用工单、用户确认及现有 worktree 的证据。按下表只读取相关分支。 +2. 开始实现前明确验收条件、集成分支、影响应用及对应目录规则;未知环境不视为已验证。 +3. 移交时保留“当前阶段、依据、下一动作、验证缺口”。交付前读取交付分支,不能以提交成功代替验收。 + +| 任务 | 读取 | +| --- | --- | +| 空白工程、大需求、技术栈或架构变化 | [建设与规格](references/planning.md) | +| 正式功能、局部 Bug、界面实现 | [实施流程](references/implementation.md) | +| 审查、推送、合并、打包、清理 | [交付流程](references/delivery.md) | +| 需要协调、执行或独立审查职责 | [角色边界](references/roles.md) | +| 调用 Matt、Superpowers、OpenSpec 或 Figma | [能力选择](references/providers.md) | + +纯咨询直接答复;无行为变化的小文字修正按影响检查,不开启完整工单/设计流程。若安装了职责重叠的技能,先按能力选择检查是否存在实际冲突,不能靠重复运行所有流程解决。 + +仅安装本 Skill 不会安装插件、创建工程配置或连接 MCP。上游缺失时可进行本技能明确的通用步骤;依赖特定工具的步骤保持待处理,不伪造调用。 diff --git a/.agents/skills/personal-dev/references/delivery.md b/.agents/skills/personal-dev/references/delivery.md new file mode 100644 index 00000000..b7a91172 --- /dev/null +++ b/.agents/skills/personal-dev/references/delivery.md @@ -0,0 +1,11 @@ +# 交付流程 + +重要业务变更需要独立审查上下文;无子代理时使用独立会话或人工审查,执行者自查不计为独立审查。按工程规则完成验证后,按已有授权推送任务分支、创建 PR、回写任务关联工单;未验证项明确列为缺口。 + +合并集成分支需要该任务的明确指令或预授权。核对审查的提交和最新目标分支;同步与解决冲突后重新验证受影响范围,合并提交,不复制 worktree 目录。 + +合并后执行集成回归,满足验收才关闭工单。集成回归失败时报告失败、保持任务未完成并处理修复;用户催促交付不能将失败改写为通过。 + +打包独立于合并。依据用户指令或预授权,在确认且验证通过的提交上创建并推送 Tag 到 Gitea,由 Drone 构建。仅有本地 Tag 不算触发;检查本次构建状态和产物。用户已确认的现有 Drone 配置不重新核查。发布 Tag 不任意移动,生产部署另按授权执行。 + +交付记录保留后,核查 worktree 内未提交和未推送内容及引用,再按工程约定清理。知识与规则变更需人工审查;当前安装器不启用夜间任务,也不自动发布复盘结论。 diff --git a/.agents/skills/personal-dev/references/implementation.md b/.agents/skills/personal-dev/references/implementation.md new file mode 100644 index 00000000..d4f7f6e5 --- /dev/null +++ b/.agents/skills/personal-dev/references/implementation.md @@ -0,0 +1,17 @@ +# 实施流程 + +## 范围与隔离 + +正式需求或 Bug 先关联工单和验收条件。按工程集成分支准备任务分支及 worktree;继续同一任务先核对已有隔离目录并复用。优先宿主原生工具,不支持目标仓库时使用工程约定 fallback。原目录的未提交改动保留原地。测试数据库、端口、密钥需独立安排;不默认访问真实业务库。 + +读取涉及应用的规则、验证命令和环境条件。局部 Bug 先复现、定位原因,再用针对性回归证明修复;功能实现以已确认规格为输入。执行测试优先覆盖实际行为,报告命令、提交、结果及未执行项,区分基线失败和新增失败。 + +## 界面 + +复杂且无工程内参考的界面先创建 Figma 原型并关联具体节点,用户验收通过才继续代码。用户明确“直到代码完成再验收”时,只免除该任务中途人工验收;原型、自检、最终验收仍保留。Figma 不可用时说明缺口,不能以直接编码等同已完成原型。简单界面或有匹配参考时复用现有模式。 + +## 工程卫生与沉淀 + +临时文件写入工程配置的本地目录;需要长期保留的有效经验整理入知识目录,并引用复现、原因、修复及验证证据。规范性结论更新对应权威规则,不仅藏在复盘里。 + +清理前核对代码、测试、脚本、部署和文档引用;名称、日期或一次检索无结果不是删除依据。生产和测试密钥存外部受控位置,仓库只记录样例、名称及来源。现有目录按职责映射,不随意新建平行体系。 diff --git a/.agents/skills/personal-dev/references/planning.md b/.agents/skills/personal-dev/references/planning.md new file mode 100644 index 00000000..39abf586 --- /dev/null +++ b/.agents/skills/personal-dev/references/planning.md @@ -0,0 +1,11 @@ +# 建设与规格 + +空白工程先从整体需求确认用户、核心业务、应用范围、验收、部署约束与技术栈,再确定目录职责及环境。只创建已确定且需要的目录;不复制试点的四应用结构或历史版本。 + +既有工程先沿用稳定选型。技术调整记录原因、影响、迁移和验证,重要选择取得用户确认后实施。 + +正式功能关联工程指定工单。新能力、业务规则、跨模块或 API 变化使用 OpenSpec:在 `openspec/changes//` 保存 proposal、design、tasks 和 specs;各产物分工,不在工单和另一套 plans 目录复制完整正文。工单保留诉求、验收与链接。 + +澄清时只问已有材料无法回答的决策。用户已经确认的阶段直接移交下一阶段,不重新完整访谈。恢复已约定行为的局部 Bug 转实施流程,保留复现/修复/回归证据;发现规范本身需要变化才升级为规格变更。 + +新工程 Gitea/Drone 按确认技术栈配置 Tag 构建与产物,通过已授权的测试 Tag 验证后才记为接通。工程配置中用户明确确认的既有 Drone 集成直接沿用,不重新审计该流水线。 diff --git a/.agents/skills/personal-dev/references/providers.md b/.agents/skills/personal-dev/references/providers.md new file mode 100644 index 00000000..554a53a0 --- /dev/null +++ b/.agents/skills/personal-dev/references/providers.md @@ -0,0 +1,18 @@ +# 能力选择与适配边界 + +本 Skill 与流程正文是原创适配层,不复制上游技能正文。工程安装器提供的 `docs/agents/personal-dev.dependencies.json` 固定候选来源及入口摘要;仅使用 npx skills 单独安装本技能时,这份依赖记录和工程配置需要另外接入。 + +| 阶段 | 候选能力 | 使用条件 | +| --- | --- | --- | +| 未完成的需求/领域澄清 | Matt Pocock grilling | 只处理尚未确认决策;已有阶段证据直接移交 | +| Bug 根因定位 | Superpowers systematic-debugging | 核对实际正文与依赖,使用一个调试主流程 | +| 实现测试循环 | Superpowers test-driven-development | 按任务范围执行;不另叠加 Matt tdd | +| 最终结果核验 | Superpowers verification-before-completion | 以实际命令证据判断,不代替独立审查 | +| 规格记录 | OpenSpec CLI/宿主入口 | 读取工程 config,按工程指定产物归属保存 | +| 复杂无参考 UI | Figma MCP | 实际授权与连接可用,按宿主必需技能操作 | + +读取实际候选技能及它引用的依赖后才决定调用。本版 doctor 的入口摘要匹配只说明一个文件相同,不能证明完整依赖已固定或行为兼容;候选组合仍待场景验收。 + +不自动串联 upstream brainstorming、writing-plans、implement 等完整主流程。已确认的设计使用本体系的阶段移交与 OpenSpec 任务;需要上游完整主流程且其硬性指令要求重复访谈或另一产物目录时,明确报告冲突,保留现场,先完成适配再调用,不能声称一句优先级规则已解决冲突。宿主已强制加载的指令仍须遵守。 + +CLI、插件、MCP 的存在、授权、连接、任务行为分别判断。缺少能力只阻塞依赖它的步骤;本地安装器不自动下载安装上游或配置账号。Figma 服务按宿主插件版本与实际调用记录验证,不把滚动服务写成固定 Git 依赖。 diff --git a/.agents/skills/personal-dev/references/roles.md b/.agents/skills/personal-dev/references/roles.md new file mode 100644 index 00000000..eab04a52 --- /dev/null +++ b/.agents/skills/personal-dev/references/roles.md @@ -0,0 +1,11 @@ +# 角色边界 + +角色是职责,不是每个任务必须创建三个代理,也不是宿主原生 Agent 配置。 + +| 角色 | 输入 | 职责与输出 | +| --- | --- | --- | +| 协调者 | 用户任务、工单、工程配置、阶段证据 | 选择任务级别与相关流程,明确当前验收和缺口;不替用户批准重要选型、界面验收或远端动作 | +| 执行者 | 已确认范围、工程规则、隔离目录 | 实现与验证,提交可审查差异及实际证据;不把自己的检查当独立审查 | +| 审查者 | 固定 base/head、任务规格、工程规范、验证记录 | 在独立上下文检查需求与规范偏差,列出有证据的阻塞和缺口;不自动修改实现或批准发布 | + +只有任务确需独立上下文且宿主允许时才创建子代理。移交保留最小必要材料,不包含密钥或原始业务数据。正式完成仍按交付流程判定。 diff --git a/.cursor/rules/personal-dev.mdc b/.cursor/rules/personal-dev.mdc new file mode 100644 index 00000000..cec7ea14 --- /dev/null +++ b/.cursor/rules/personal-dev.mdc @@ -0,0 +1,6 @@ +--- +description: 个人开发体系的工程任务入口 +alwaysApply: true +--- + +工程建设、需求开发、Bug 修复或交付时,先读根 AGENTS.md,再读取工程根目录的 .agents/skills/personal-dev/SKILL.md 进行任务分级。仅咨询概念时直接回答。业务约束仍按目标目录的 AGENTS.md 查阅。 diff --git a/.gitignore b/.gitignore index e3be4009..cd6b48d3 100644 --- a/.gitignore +++ b/.gitignore @@ -113,3 +113,7 @@ exports/ # 本地密钥(勿提交) 测试环境机器的账号密码 + +# personal-dev:begin +/.local/agent/ +# personal-dev:end diff --git a/AGENTS.md b/AGENTS.md index 3be651c3..9e99f51b 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -53,3 +53,7 @@ - 业务历史方案、执行计划、Demo 与整理报告已清理;保留四个应用目录、现行工程规范及被部署或脚本读取的 SQL、SOP 等资源。 - 文档优先更新现有 README 或规范入口,避免重复生成历史业务方案和整理报告。 - 更改规则应同步唯一的对应入口,不在多个文件复制完整细则。 + + +工程建设、需求开发、Bug 修复或交付时,读取 [个人开发入口](.agents/skills/personal-dev/SKILL.md),并按需查阅 [工程配置](docs/agents/README.md)。业务约束继续遵循目标目录规则;纯咨询无需启动开发流程。 + diff --git a/docs/agents/README.md b/docs/agents/README.md new file mode 100644 index 00000000..6b72772a --- /dev/null +++ b/docs/agents/README.md @@ -0,0 +1,15 @@ +# 工程接入配置 + +`project.json` 是工程自行维护的输入;安装器升级保留它。路径以工程根目录为基准,未知值用 null 或空列表,不能把未知写成验证通过。 + +- `project`:项目名称、discovery/existing 阶段、集成分支、工单仓库;分支不会默认取当前任务分支。 +- `apps`:每项提供 name、path、rules 与 validation。validation 是命令/环境说明列表,安装器不会执行。 +- `decisions`:已确认技术栈与架构决策的文档路径;新工程在开发前确认,既有工程先沿用。 +- `worktree`:优先原生机制,fallback 为工程约定的隔离目录;数据库与端口另行隔离。 +- `figma`:具体文件/节点引用与状态;配置存在不代表授权或连接成功。 +- `delivery`:Drone + Tag;status 可为 unverified 或 user-confirmed,evidence 记录用户确认依据。用户确认已完成时不安排重复核查;每次实际打包仍检查结果。 +- `permissions`:仅记录工程事先授予的动作范围,true 必须有用户授权依据;不覆盖宿主限制和当前会话指令。默认 false,已有任务明确授权不重复询问。 +- `environment`:记录测试环境条件和外部密钥来源说明,禁止填写凭据值;生产/测试隔离。 +- `knowledge`:审核后知识与本地报告位置。本版未提供自动调度,schedule_enabled 必须为 false。 + +各端专用规范继续保留在原位置。任务从工程根目录的 `.agents/skills/personal-dev/SKILL.md` 进入,按需读取其 references。复用上游前核对 `personal-dev.dependencies.json` 中来源;doctor 只检查本地存在与候选入口摘要,不证明完整依赖、宿主调用或远端连接可用。 diff --git a/docs/agents/personal-dev.dependencies.json b/docs/agents/personal-dev.dependencies.json new file mode 100644 index 00000000..43e9816e --- /dev/null +++ b/docs/agents/personal-dev.dependencies.json @@ -0,0 +1,61 @@ +{ + "schema_version": 1, + "status": "candidate-not-behavior-verified", + "mode": "external-reference-only", + "sources": [ + { + "repo": "mattpocock/skills", + "commit": "a496f5513d4a4cf889bc48e189e579f4b0bdf6aa", + "license": "MIT", + "license_path": "LICENSE", + "skills": [ + { + "name": "grilling", + "path": "skills/productivity/grilling/SKILL.md", + "sha256": "a146842ed93ca43d833550fa9adf02e58cb63c83fea9d4b4522995b82242d4e2" + } + ] + }, + { + "repo": "obra/superpowers", + "commit": "2ce8aa15d05bd57213e6f746f953aafb7ded7a8b", + "license": "MIT", + "license_path": "LICENSE", + "skills": [ + { + "name": "systematic-debugging", + "path": "skills/systematic-debugging/SKILL.md", + "sha256": "51c6435d98c83c42c96ba7c35725a0b2c376cd487fb1a4e6bd0ddbe7e33ef202" + }, + { + "name": "test-driven-development", + "path": "skills/test-driven-development/SKILL.md", + "sha256": "64b03fce4aee5a97a93160cea8111f3ba13a17b7c001db4bd5836d67fd10705d" + }, + { + "name": "verification-before-completion", + "path": "skills/verification-before-completion/SKILL.md", + "sha256": "2befe7fc55bcadaa3d97dd9e8efeb633d2561c0ebe74c5a8b17c4d9e7e4520b3" + } + ] + }, + { + "repo": "Fission-AI/OpenSpec", + "commit": "6d04a1b58dedc95729d34e4f223d9d483aae210a", + "license": "MIT", + "license_path": "LICENSE", + "skills": [], + "mode": "external-cli-not-installed-by-pda" + } + ], + "figma": { + "mode": "host-mcp", + "version": "record-host-plugin-version-at-validation", + "connection": "not-checked" + }, + "notes": [ + "Upstream content is not redistributed or modified.", + "Only entry file hashes are pinned; transitive assets and behavior remain unverified.", + "No automatic dependency installation or background upgrades." + ] +} diff --git a/docs/agents/personal-dev.lock.json b/docs/agents/personal-dev.lock.json new file mode 100644 index 00000000..8a181bb3 --- /dev/null +++ b/docs/agents/personal-dev.lock.json @@ -0,0 +1,18 @@ +{ + "schema_version": 1, + "files": { + "docs/agents/README.md": "e5379c2e2eeb61b07c194656c110ff4d9af77d07da956aa11f07469900273488", + "docs/agents/personal-dev.dependencies.json": "d4f2d0eceef8700fbadda33644e129dcc8d684cc09596db69fd19735b02b1f59", + ".cursor/rules/personal-dev.mdc": "41ac0394be74878c9029f775deb9991b4a0292773fde02e7a4a9da22ffaeb15e", + ".agents/skills/personal-dev/SKILL.md": "6eb0c6f738586876b8ebf4227178d6a9b120fdc14e61c6b4c0cbd359239b4cb8", + ".agents/skills/personal-dev/references/delivery.md": "03255455a2a5a2183fd6162ea8c368b01d14d6d1589a14b80b1222692fe93c59", + ".agents/skills/personal-dev/references/implementation.md": "688db2826b65ccc6b3e9b9f82494afd02c1d4301f49eaa62c9d0d344f09c8bff", + ".agents/skills/personal-dev/references/planning.md": "cdfe556e1c59cc2b3b56ed41dc60ae6ca27df0a5ce2f0fc63a44092986b1ed29", + ".agents/skills/personal-dev/references/providers.md": "510d13ad996e8e1cb541d908a17ebcf3a849bab028685f6a497ba0d68bf5295b", + ".agents/skills/personal-dev/references/roles.md": "61530733d4b7fd037f04671dd7d0a20a24c1522c1accb51ed2cf1b06fe00cd9d" + }, + "blocks": { + "AGENTS.md": "d40f6daf1e33b73049df8b2145140c57d69c295f3cab13ba2323829caf84df2a", + ".gitignore": "8d8aed371a09669dcdafcc43f8825b5e284a30e9ae1ad26c8c61bd8a88a45751" + } +} diff --git a/docs/agents/project.json b/docs/agents/project.json new file mode 100644 index 00000000..8d1f71be --- /dev/null +++ b/docs/agents/project.json @@ -0,0 +1,90 @@ +{ + "schema_version": 1, + "project": { + "name": "zkxw", + "stage": "existing", + "integration_branch": "V2.0", + "tracker": { + "kind": "gitea", + "repository": "https://gitea.aichengyan.com/cykj/zkxw" + } + }, + "apps": [ + { + "name": "backend", + "path": "backend", + "rules": "backend/AGENTS.md", + "validation": [ + { + "command": "python backend/scripts/check_field_consistency.py", + "environment": "工程根目录;仅覆盖注册实体,已知路径限制见 docs/dev-field-consistency.md;业务测试另按 backend/AGENTS.md 在隔离环境选择" + } + ] + }, + { + "name": "mobile-h5", + "path": "mobile-h5", + "rules": "mobile-h5/AGENTS.md", + "validation": [] + }, + { + "name": "mobile-oa-h5", + "path": "mobile-oa-h5", + "rules": "mobile-oa-h5/AGENTS.md", + "validation": [ + { + "command": "npm --prefix mobile-oa-h5 run build", + "environment": "已安装该应用依赖;另需按应用规则运行受影响测试与 WebView 真机验收" + } + ] + }, + { + "name": "web-admin", + "path": "web-admin", + "rules": "web-admin/AGENTS.md", + "validation": [ + { + "command": "pnpm --dir web-admin build", + "environment": "已安装对应依赖;构建可能包含类型检查,按 package.json 核对;不启动开发服务" + } + ] + } + ], + "decisions": { + "tech_stack": "README.md", + "architecture": null + }, + "worktree": { + "strategy": "native-first", + "fallback": ".local/agent/worktrees" + }, + "figma": { + "references": [ + "https://www.figma.com/design/jc7D8Fe7lKNTVj4jM3AoGW?node-id=2-2" + ], + "status": "user-confirmed-demo-only" + }, + "delivery": { + "provider": "drone", + "trigger": "tag", + "status": "user-confirmed", + "evidence": "用户确认既有 Gitea/Drone Tag 打包已完成,本次不复查或修改流水线。" + }, + "permissions": { + "push_task_branch": false, + "create_pr": false, + "write_issue": false, + "merge": false, + "push_tag": false, + "deploy": false + }, + "environment": { + "test": "由各任务确认独立测试环境;此接入未连接业务数据库,不启动或重启服务。", + "secrets": "external-controlled-storage" + }, + "knowledge": { + "directory": "docs/knowledge", + "reports": ".local/agent/retros", + "schedule_enabled": false + } +}