From 23f7de6cbf3ce94e286464b75d4c9687d92700f5 Mon Sep 17 00:00:00 2001
From: caoxiaozhu <caoxiaozhu@users.noreply.github.com>
Date: Thu, 25 Jun 2026 09:19:37 +0800
Subject: [PATCH] chore(skills): add development docs writer

---
 .codex/skills/write-development-docs/SKILL.md | 103 ++++++++++++++
 .../write-development-docs/agents/openai.yaml |   4 +
 .../write-development-docs/assets/CONCEPT.md  | 130 ++++++++++++++++++
 .../write-development-docs/assets/TODO.md     |  71 ++++++++++
 .gitignore                                    |   2 +
 document/work-log/2026-06-25.md               |  19 +++
 6 files changed, 329 insertions(+)
 create mode 100644 .codex/skills/write-development-docs/SKILL.md
 create mode 100644 .codex/skills/write-development-docs/agents/openai.yaml
 create mode 100644 .codex/skills/write-development-docs/assets/CONCEPT.md
 create mode 100644 .codex/skills/write-development-docs/assets/TODO.md
 create mode 100644 document/work-log/2026-06-25.md

diff --git a/.codex/skills/write-development-docs/SKILL.md b/.codex/skills/write-development-docs/SKILL.md
new file mode 100644
index 0000000..7d040f0
--- /dev/null
+++ b/.codex/skills/write-development-docs/SKILL.md
@@ -0,0 +1,103 @@
+---
+name: write-development-docs
+description: Use when working in X-Financial and the user asks to 落文档, 写开发文档, 沉淀方案, 补 concept/todo, or create/update planning documentation under document/development for a feature, refactor, page, algorithm, rule, or business capability.
+---
+
+# Write Development Docs
+
+## 目标
+
+把一个功能、重构、算法、页面或业务能力沉淀为项目标准开发文档。
+默认落点固定为：
+
+```text
+document/development/<功能目录>/
+├── CONCEPT.md
+└── TODO.md
+```
+
+如果用户说 `concept.md` / `todo.md`，也按仓库现有规范使用大写文件名
+`CONCEPT.md` 和 `TODO.md`。
+
+## 工作流
+
+1. 先阅读 `document/development` 中 2-3 组相邻或同类样例。
+2. 再读取本次能力相关的代码、接口、页面、测试或历史文档。
+3. 创建或更新 `CONCEPT.md`，先写清业务边界，再写方案和验收。
+4. 创建或更新 `TODO.md`，每个任务都要回链到 `CONCEPT.md` 的章节。
+5. 已实现或已验证的 TODO 可以勾选 `[x]`，但必须写证据。
+6. 交付前检查两份文档互相一致，不额外创建 README、CHANGELOG、SUMMARY。
+
+## 目录命名
+
+- 优先复用用户指定目录名或已有目录名。
+- 新增英文目录用小写 kebab-case，例如 `receipt-folder`。
+- 新增中文目录可直接用清晰中文能力名，例如 `费用审批动态路由`。
+- 同一能力已有目录时更新原目录，不新建近义目录。
+
+## CONCEPT.md 要求
+
+可参考 `assets/CONCEPT.md` 模板。必须包含：
+
+- 标题：`# <功能名> 概念文档`
+- `更新时间：YYYY-MM-DD`
+- `## 功能一句话`
+- `## 背景与问题`
+- `## 目标与非目标`
+- `## 用户与场景`
+- `## 功能能力`
+- `## 方案设计`
+- `## 算法与公式`
+- `## 测试方案`
+- `## 指标与验收`
+- `## 风险与开放问题`
+
+写法要求：
+
+- 先讲业务问题和边界，再讲技术方案。
+- 目标与非目标分开写，避免需求无限扩张。
+- 方案设计按前端、后端、算法/规则、数据、权限、降级策略分块；
+  不涉及的块明确写“当前不涉及”。
+- 算法与公式必须明确“不涉及”或写出公式、变量说明和适用边界。
+- 验收标准必须可验证，不写空泛口号。
+
+## TODO.md 要求
+
+可参考 `assets/TODO.md` 模板。必须包含：
+
+- 标题：`# <功能名> 开发 TODO`
+- `更新时间：YYYY-MM-DD`
+- `## 使用规则`
+- 分阶段 checklist
+
+TODO 条目规则：
+
+- 每条用 `- [ ]` 或 `- [x]`。
+- 每条必须包含 `[CONCEPT: <章节名>]`。
+- 已完成项必须补证据，格式为 `证据：<文件、接口、命令或验证结果>`。
+- 没有真实证据时不得勾选 `[x]`。
+
+建议阶段：
+
+- `## 1. 调研与边界`
+- `## 2. 契约与设计`
+- `## 3. 后端实现`
+- `## 4. 算法/规则实现`
+- `## 5. 前端实现`
+- `## 6. 测试与验证`
+- `## 7. 文档收尾`
+
+## 更新既有文档
+
+- 先读现有 `CONCEPT.md` 和 `TODO.md` 全文。
+- 新需求先补 `CONCEPT.md`，再补 `TODO.md`。
+- 实现变化时同步更新“非目标”“风险与开放问题”“本轮实现记录”。
+- 不删除历史证据；除非证据明显错误，才替换为新证据。
+
+## 验收检查
+
+- 两个文件都位于 `document/development/<功能目录>/`。
+- `CONCEPT.md` 和 `TODO.md` 都存在。
+- TODO 的 `[CONCEPT: ...]` 都能在 CONCEPT 中找到对应章节或语义段落。
+- 已勾选项都有证据。
+- 文档没有遗留模板占位符，例如 `<功能名>`、`<YYYY-MM-DD>`、`待补充`。
diff --git a/.codex/skills/write-development-docs/agents/openai.yaml b/.codex/skills/write-development-docs/agents/openai.yaml
new file mode 100644
index 0000000..b5562d6
--- /dev/null
+++ b/.codex/skills/write-development-docs/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+  display_name: "开发文档落地"
+  short_description: "按项目格式生成 CONCEPT 和 TODO 文档"
+  default_prompt: "Use $write-development-docs to create CONCEPT.md and TODO.md under document/development for an X-Financial feature."
diff --git a/.codex/skills/write-development-docs/assets/CONCEPT.md b/.codex/skills/write-development-docs/assets/CONCEPT.md
new file mode 100644
index 0000000..995a127
--- /dev/null
+++ b/.codex/skills/write-development-docs/assets/CONCEPT.md
@@ -0,0 +1,130 @@
+# <功能名> 概念文档
+
+更新时间：<YYYY-MM-DD>
+
+## 功能一句话
+
+用一句话说明这个能力解决什么问题、服务谁、交付什么结果。
+
+## 背景与问题
+
+- 当前现状：
+- 用户痛点：
+- 业务影响：
+- 为什么现在需要做：
+
+## 目标与非目标
+
+### 目标
+
+- [G1]
+- [G2]
+- [G3]
+
+### 非目标
+
+- [NG1] 本轮不做：
+- [NG2] 本轮不改变：
+- [NG3] 后续再评估：
+
+## 用户与场景
+
+- 目标用户：
+- 使用入口：
+- 核心场景：
+  1.
+  2.
+  3.
+- 异常场景：
+  -
+
+## 功能能力
+
+- [C1] 输入能力：
+- [C2] 处理能力：
+- [C3] 输出能力：
+- [C4] 状态与权限：
+- [C5] 边界与降级：
+
+## 方案设计
+
+### 前端
+
+- 页面/组件：
+- 交互状态：
+- 展示规则：
+- 降级处理：
+
+### 后端
+
+- 接口/服务：
+- 权限与校验：
+- 持久化：
+- 降级处理：
+
+### 算法与规则
+
+- 输入：
+- 流程：
+- 输出：
+- 解释：
+
+### 数据与契约
+
+- 核心字段：
+- 状态枚举：
+- 兼容策略：
+- 版本/审计：
+
+## 算法与公式
+
+当前功能不涉及显式数学公式。
+
+如涉及公式，使用如下格式：
+
+```text
+metric = input_a + input_b
+```
+
+变量说明：
+
+- metric：
+- input_a：
+- input_b：
+
+## 测试方案
+
+后端：
+
+-
+
+前端：
+
+-
+
+集成：
+
+-
+
+手工验证：
+
+-
+
+## 指标与验收
+
+- [A1] 功能验收：
+- [A2] 性能指标：
+- [A3] 质量指标：
+- [A4] 安全/权限指标：
+- [A5] 可观测性：
+
+## 风险与开放问题
+
+- 风险：
+- 已处理依赖：
+- 待确认：
+- 降级策略：
+
+## 本轮实现记录
+
+-
diff --git a/.codex/skills/write-development-docs/assets/TODO.md b/.codex/skills/write-development-docs/assets/TODO.md
new file mode 100644
index 0000000..2092a7d
--- /dev/null
+++ b/.codex/skills/write-development-docs/assets/TODO.md
@@ -0,0 +1,71 @@
+# <功能名> 开发 TODO
+
+更新时间：<YYYY-MM-DD>
+
+## 使用规则
+
+- 每个 TODO 必须对应 `CONCEPT.md` 中的目标、能力、方案或验收点。
+- 只有完成并验证后，才能把 `[ ]` 改成 `[x]`。
+- 勾选时在任务后补充简短证据，例如文件、接口、命令或验证结果。
+- 如果需求发生变化，先更新 `CONCEPT.md`，再调整本 TODO。
+
+## 1. 调研与边界
+
+- [ ] [CONCEPT: 背景与问题] 阅读相关页面、接口、服务、测试和历史文档，记录当前实现事实。
+  证据：
+- [ ] [CONCEPT: 目标与非目标] 确认本轮开发范围，写清楚不做项。
+  证据：
+- [ ] [CONCEPT: 风险与开放问题] 标记无法立即确认的依赖、风险和假设。
+  证据：
+
+## 2. 契约与设计
+
+- [ ] [CONCEPT: 功能能力] 定义输入、输出、状态、权限和边界条件。
+  证据：
+- [ ] [CONCEPT: 方案设计] 明确前端、后端、算法、数据的职责边界。
+  证据：
+- [ ] [CONCEPT: 算法与公式] 补全公式、变量解释或明确当前不涉及公式。
+  证据：
+- [ ] [CONCEPT: 指标与验收] 把验收标准转成可验证的检查点。
+  证据：
+
+## 3. 后端实现
+
+- [ ] [CONCEPT: 后端] 新增或调整 schema、service、endpoint、权限和持久化逻辑。
+  证据：
+- [ ] [CONCEPT: 数据与契约] 保持响应结构、状态枚举和兼容策略清晰。
+  证据：
+
+## 4. 算法/规则实现
+
+- [ ] [CONCEPT: 算法与规则] 实现核心处理流程、规则判断或计算逻辑。
+  证据：
+- [ ] [CONCEPT: 结果解释] 输出可读解释、证据链、贡献项或降级原因。
+  证据：
+
+## 5. 前端实现
+
+- [ ] [CONCEPT: 前端] 新增或调整页面、组件、服务 API 和视图模型。
+  证据：
+- [ ] [CONCEPT: 前端] 实现加载、空态、错误态、权限态和刷新。
+  证据：
+- [ ] [CONCEPT: 前端] 对齐现有企业后台风格，避免营销页或花哨卡片感。
+  证据：
+
+## 6. 测试与验证
+
+- [ ] [CONCEPT: 测试方案] 补充后端 service/API 定向测试，容器内运行，超时控制在 60s 内。
+  证据：
+- [ ] [CONCEPT: 测试方案] 补充前端视图模型、路由、组件或构建验证。
+  证据：
+- [ ] [CONCEPT: 指标与验收] 记录验证命令、结果和未覆盖风险。
+  证据：
+
+## 7. 文档收尾
+
+- [ ] [CONCEPT: 指标与验收] 回看所有验收点，确认均有实现或验证证据。
+  证据：
+- [ ] [CONCEPT: 风险与开放问题] 更新剩余风险、后续任务和明确不做项。
+  证据：
+- [ ] [CONCEPT: 功能一句话] 确认最终实现没有偏离原始目标。
+  证据：
diff --git a/.gitignore b/.gitignore
index 5cc503a..ea8ae16 100644
--- a/.gitignore
+++ b/.gitignore
@@ -15,6 +15,8 @@ web/.vite/
 !.codex/skills/agent-change-log/**
 !.codex/skills/git-checkpoint-commit/
 !.codex/skills/git-checkpoint-commit/**
+!.codex/skills/write-development-docs/
+!.codex/skills/write-development-docs/**
 .codex-temp/
 .superpowers/
 *.log
diff --git a/document/work-log/2026-06-25.md b/document/work-log/2026-06-25.md
new file mode 100644
index 0000000..c328cde
--- /dev/null
+++ b/document/work-log/2026-06-25.md
@@ -0,0 +1,19 @@
+# 2026-06-25 工作日志
+
+## 当日工作内容
+
+- 09:18：我完成了项目级 `write-development-docs` 技能落地。
+  - Git 提交检查：`git fetch --all --prune` 后未发现 `HEAD..origin/main` 或 `origin/main..HEAD` 新提交；工作区已有多处未提交改动，本次只处理 `.codex/skills/write-development-docs` 和 `.gitignore`。
+  - 修改：新增 `.codex/skills/write-development-docs/SKILL.md`、`agents/openai.yaml`、`assets/CONCEPT.md`、`assets/TODO.md`，把“落文档”请求固化为 `document/development/<功能目录>/CONCEPT.md + TODO.md` 两文件流程。
+  - 修改：补充 `.gitignore` allowlist，确保 `write-development-docs` 技能文件不会被 `.codex/skills/*` 忽略规则挡住。
+  - 操作：先读取 `document/development` 既有样例和 `hermes/skills/domain/write-development-docs` 旧版技能，再用 `init_skill.py` 生成标准 Skill 骨架并收口为项目规范。
+  - 验证：`frontmatter ok`、`required files ok`、`.codex/skills/write-development-docs` 无 `[TODO:]` 初始化占位符，`git diff --check -- .codex/skills/write-development-docs .gitignore` 通过。
+  - 影响：以后用户说“落文档 / 写开发文档 / 补 concept 和 todo”时，可以优先触发仓库级技能，按项目格式生成两份开发文档。
+
+## 遗留问题
+
+- 09:18：官方 `quick_validate.py` 仍因当前 Python 环境缺少 `PyYAML` 无法运行，已用 frontmatter、必需文件、占位符和 diff check 做人工兜底。建议后续统一为 skill 校验脚本补齐依赖或增加无 PyYAML 的轻量校验路径。
+
+## TODO
+
+- [ ] 为 `quick_validate.py` 准备稳定运行环境，避免后续新增 Skill 时继续依赖人工兜底。（来源：09:18 技能校验）