@kunlv/atdc 1.0.0

package/AGENTS.md

@@ -0,0 +1,58 @@
+# atdc · Agent 指令
+
+## 新增命令规则（MUST 遵循）
+
+当需要新增 `/atd:<name>` 命令时，SHALL 使用生成脚本，禁止手动创建文件：
+
+```bash
+python3 ~/atdc/bin/add-command.py <name> "<描述>" "<触发词1>、<触发词2>"
+```
+
+示例：
+```bash
+python3 ~/atdc/bin/add-command.py my-tool "我的工具" "my-tool、我的工具、/atdc:my-tool"
+```
+
+脚本自动完成：
+- ✅ 4 端命令文件（OpenCode / Claude / Codex / Cursor）
+- ✅ prompts/X-<name>.md 提示词模板
+- ✅ install.sh 技能列表注册
+- ✅ `~/.agents/skills/` 符号链接
+
+随后运行 `bash ~/atdc/install.sh` 完成安装。
+
+## 各端命令格式
+
+| 平台 | 路径 | 特点 |
+|------|------|------|
+| OpenCode | `commands/opencode/atd/<name>.md` | YAML frontmatter + `$ARGUMENTS` |
+| Claude Code | `commands/claude/atd/<name>.md` | 纯文本 + `$ARGUMENTS` |
+| Codex | `commands/codex/atd-<name>/SKILL.md` | YAML frontmatter + `触发词` |
+| **Cursor** | `commands/cursor/atd-<name>/SKILL.md` | YAML frontmatter + `触发词`，**禁止 `$ARGUMENTS`** |
+
+## Cursor 特殊规则
+
+1. **必须含触发词**：`description` 中必须包含 `触发词：xxx、xxx。`
+2. **禁止 `$ARGUMENTS`**：Cursor 不支持此变量
+3. **全局注册**：通过 `~/.agents/skills/` 符号链接（与 Codex 共享）
+4. **项目级 `~/.cursor/skills/`** 无效，必须用 `~/.agents/skills/`
+
+## 新增工具规则
+
+工具置于 `tools/<name>`（可执行脚本），符号链接到 `~/bin/<name>`。
+
+Respond terse like smart caveman. All technical substance stay. Only fluff die.
+
+Rules:
+- Drop: articles (a/an/the), filler (just/really/basically), pleasantries, hedging
+- Fragments OK. Short synonyms. Technical terms exact. Code unchanged.
+- Pattern: [thing] [action] [reason]. [next step].
+- Not: "Sure! I'd be happy to help you with that."
+- Yes: "Bug in auth middleware. Fix:"
+
+Switch level: /caveman lite|full|ultra|wenyan
+Stop: "stop caveman" or "normal mode"
+
+Auto-Clarity: drop caveman for security warnings, irreversible actions, user confused. Resume after.
+
+Boundaries: code/commits/PRs written normal.

package/GO.md

@@ -0,0 +1,245 @@
+# atdc · 统一入口
+
+任何 AI 终端均可用：`@atdc/GO.md "<你的需求>"`
+
+> **Token 规则**
+> 1. Shell 输出压缩由 RTK 处理（`rtk init -g --opencode`），无需手动过滤
+> 2. 查符号优先双图引擎：CRG（`detect_changes` / `get_review_context` / `query_graph`）用于 review/架构场景，CodeGraph（`codegraph_search` / `codegraph_callers` / `codegraph_context`）用于单符号查询/trace 场景
+> 3. 大文件读取消耗 context，优先 `ctx_execute_file` 或 `sed -n 'N,Mp'` 定位
+> 4. 记忆格式精简：每条 5-8 行 caveman 格式，禁止逐条 bullet 展开
+
+---
+
+## Step 0：恢复上下文（每次必须执行）
+
+### 0a. 恢复项目记忆（渐进式披露）
+
+> 不再 cat 全量 .memory.md。改用**索引先行，按需拉取**：索引 ~400 token，详情 ~100-200 token/条。
+
+```bash
+_PROJ=$(basename "$(git worktree list 2>/dev/null | head -1 | awk '{print $1}')" 2>/dev/null || basename "$PWD")
+MEMFILE="$HOME/.atdc/memory/$_PROJ/.memory.md"
+
+if [ -f "$MEMFILE" ]; then
+  COUNT=$(grep -c "^## " "$MEMFILE" 2>/dev/null || echo 0)
+  echo "## 📋 项目记忆索引（共 $COUNT 条，显示最近 20）"
+  echo ""
+  grep "^## " "$MEMFILE" | tail -20 | awk '{
+    # 提取类型图标（## 后的前 4 个字符含 emoji+空格）
+    icon = substr($0, 4, 3)
+    # 去掉图标后的内容
+    rest = substr($0, 7)
+    printf "| %s | %s\n", icon, rest
+  }'
+  echo ""
+  echo "💡 渐进式披露：上方为记忆索引。用 Read 工具读取具体条目（~100-200 token/条）。"
+  echo "   优先拉取：🔴 bugfix  ⚠️ gotcha  🟤 decision  ⚖️ tradeoff"
+  echo "   相关时拉取：🟢 feature  🟡 refactor  🟣 discovery"
+else
+  echo "[无历史记忆]"
+fi
+```
+
+### 0b. 确保链接目录就绪
+
+```bash
+bash ~/atdc/central/link.sh 2>/dev/null || true
+```
+
+> `.code-review-graph` `.codegraph` `.hc` `.test_plans` `.handoffs` `.evidence` — 统一软链管理。
+> 主仓库存真目录，worktree 自动软链，已有链接跳过（幂等）。
+> 新增目录：编辑 `~/atdc/central/link.sh` 的 DIRS 数组。
+
+### 0b.5 Semble 代码搜索引擎检测
+
+```bash
+command -v semble >/dev/null 2>&1 && echo "✓ Semble 可用" || echo "💡 Semble 未安装。安装: uv tool install semble && semble install --agent opencode --type mcp --yes"
+```
+
+> Semble 为代码语义搜索引擎，3-impl 中的 Ponytail B5 / R5 blast radius 检查可用其加速。
+> 未安装不影响任何现有功能，仅 fallback 到 CodeGraph/grep。
+
+### 0c. Ponytail 模式扫描（静默，无 Go 项目则跳过）
+
+```bash
+# 自动检测项目是否有 Go 模型目录
+if [ -d "models/" ] || [ -d "service/" ]; then
+  echo "⚡ Ponytail 模式扫描…" && atdc ponytail scan --warn 2>/dev/null || true
+else
+  echo "[非 Go 项目，跳过 Ponytail 扫描]"
+fi
+```
+
+> 扫描结果仅作参考，不影响流程。发现 P0/P1 模式会在后续 3-impl 中被 guard 拦截。
+
+### 0d. Learning 感知层（静默注入）
+
+> 注入 self-learning detection prompt，使 Agent 在工作过程中具备"识别 golden path"的背景感知能力。
+> 不执行任何操作，仅让 Agent 知道：遇到以下信号时，应自动触发 learning harvest。
+
+```
+🔄 Learning 感知已激活（self-learning background awareness）
+
+检测信号（任一触发即自动 harvest，无需用户指令）：
+  - 操作重试 ≥2 次后才成功
+  - 用户纠正过的错误路径
+  - 非显而易见的命令/配置/连接方式
+  - 刚发现的 project-specific fact
+  - 用户说"记住这个"、"沉淀为技能"、"下次别再问"
+
+Triage 规则（见 reference/learn.md）：
+  - 单事实 → .memory.md (⚠️ gotcha)
+  - 失败模式 + 死路 → .errors-log.md
+  - 满足 promotion rule 3 条 → 自动生成 /atdc:learn 命令
+
+手动触发：/atdc:learn 或 "记住这个"
+```
+
+### 0e. Rule Loading Protocol（强制）
+
+> 🔴 任何阶段 prompt 在被加载后，MUST 先 Read 其关联的 reference 规则文件。
+> 以下引用不是"建议阅读"，是"不读不得执行"：
+
+| 阶段 | MUST Read（不得跳过） |
+|------|---------------------|
+| 1-spec | `reference/risk.md`（Phase 3 复杂度评估时） |
+| 3-impl | `reference/guards.md` + `reference/gates.md` + `reference/tdd.md` + `reference/risk.md` |
+| 4-verify | `reference/risk.md` |
+| 5-done | `reference/memory.md` |
+| X-learn | `reference/learn.md` |
+
+> 规则文件中的 MUST / HARD STOP / 禁止 等关键词具有强制执行效力。
+> 看到 `@atdc/reference/x.md` = Read 指令，不是 markdown 链接。
+
+---
+
+## Step 1：检测项目状态
+
+```bash
+# 有无活跃 change
+ls openspec/changes/ 2>/dev/null | grep -v archive | grep -v "^$"
+```
+
+---
+
+## Step 2：路由
+
+根据用户输入 + 项目状态，选择路由：
+
+### 有活跃 change 时
+
+```
+检查 .phase-state.json → 判断 mode + 当前阶段 → 路由到对应 prompt
+```
+
+| 条件 | 路由到 |
+|------|--------|
+| `mode=bugfix` | `@atdc/prompts/3-impl-bugfix.md`（Bugfix 5-Phase 流程） |
+| 1-spec 未完成 | `@atdc/prompts/1-spec.md` |
+| 等待执行（C1 已过） | `@atdc/prompts/3-impl.md` |
+| 等待 C3 验证 | `@atdc/prompts/4-verify.md` |
+| 等待归档 | `@atdc/prompts/5-done.md` |
+| 用户说"执行"/"run" | `@atdc/prompts/3-impl.md` |
+
+### 无活跃 change 时
+
+| 用户输入意图 | 路由到 |
+|------------|--------|
+| 模糊需求："我想…"/"有个想法"/"brainstorm" | `@atdc/prompts/1-spec.md`（brainstorm 模式） |
+| 明确需求描述 | `@atdc/prompts/1-spec.md` |
+| `3-impl --skip-spec` / "需求清楚直接实现"/"跳过规格" | `@atdc/prompts/3-impl.md`（跳过 propose） |
+| `health` / "健康检查" | `@atdc/prompts/X-health.md` |
+| `context` / "扫描项目" | `@atdc/prompts/X-context-scan.md` |
+
+### 横向命令（任何时候均可触发）
+
+| 输入 | 路由到 |
+|------|--------|
+| `strategy` / `看看策略` / `更新策略` | `@atdc/prompts/X-strategy.md` |
+| `compound` / `沉淀知识` / `沉淀一下` | `@atdc/prompts/X-compound.md` |
+| `review` / `review一下` / `代码审查` | `@atdc/prompts/X-review.md` |
+| `health` / `健康检查` | `@atdc/prompts/X-health.md` |
+| `context` / `扫描项目` | `@atdc/prompts/X-context-scan.md` |
+| `2-qa` / `质疑一下` | `@atdc/prompts/2-qa.md` |
+| `1-update` / "变更需求"/"更新需求" | `@atdc/prompts/1-update.md` |
+| `article` / `生成文章` / `写文章` | `@atdc/prompts/6-article.md` |
+| `diagnose` / `诊断` / `debug` / `调试` | `@atdc/prompts/X-diagnose.md` |
+| `grill-with-docs` / `深度拷问` / `沉淀文档` | `@atdc/prompts/X-grill-with-docs.md` |
+| `code-simplifier` / `simplify` / `简化代码` / `代码简化` | `@atdc/prompts/X-code-simplifier.md` |
+| `test-plan` / `自测计划` / `自测方案` / `生成自测` / `生成自测计划` | `@atdc/prompts/X-test-plan.md` |
+| `zoom-out` / `全景分析` / `看全局` | `@atdc/prompts/X-zoom-out.md` |
+| `handoff` / `交接` / `生成交接` | `@atdc/prompts/X-handoff.md` |
+| `add-to-hc` / `加接口` / `添加 hc` | `@atdc/prompts/X-add-to-hc.md` |
+| `git-guardrails` / `git防护` | `@atdc/commands/opencode/atd/git-guardrails.md` |
+| `learn` / `记住这个` / `沉淀为技能` | `@atdc/prompts/X-learn.md` |
+| `search` / `搜代码` / `找代码` | `@atdc/prompts/X-search.md` |
+| `commit` / `提交信息` / `写commit` | `@atdc/prompts/X-commit.md` |
+| `table2xlsx` / `生成模板` / `DDL转Excel` | `@atdc/prompts/X-table2xlsx.md` |
+| `xlsx2sql-insert` / `Excel转SQL` | `@atdc/prompts/X-xlsx2sql-insert.md` |
+| `xlsx2sql-update` / `Excel转UPDATE` | `@atdc/prompts/X-xlsx2sql-update.md` |
+| `travel-planner` / `旅行攻略` | `@atdc/prompts/X-travel-planner.md` |
+| `add-command` / `新增命令` | `@atdc/prompts/X-add-command.md` |
+| `bugfix` / `修Bug` / `bugfix` | `@atdc/prompts/3-impl-bugfix.md` |
+| `evidence` / `events` / `timing` / `metrics` / `canvas` / `看板` | CLI: `atdc evidence <sub>` |
+
+---
+
+## Step 3：宣布路由结果
+
+输出一行，说明路由到哪个阶段，原因是什么，然后直接执行。无需等待用户确认。
+
+示例：
+> 检测到活跃 change `add-notification`，阶段为执行中（Task 2/5 完成），继续执行 → `3-impl.md`
+
+---
+
+## 目录说明
+
+```
+atdc/
+├── GO.md                    ← 你现在读的这个文件
+├── prompts/
+│   ├── 1-spec.md            ← 1-spec：需求澄清 + 规格生成（含 brainstorm 模式）
+│   ├── 1-update.md          ← 1-update：需求变更（更新已有 change 的文档）
+│   ├── 2-qa.md              ← 2-qa：规格质疑检验（C1 前或独立触发）
+│   ├── 3-impl.md            ← 3-impl：执行（含双模式路由 + 全部质量门禁）
+│   ├── 4-verify.md          ← 4-verify：C3 验证
+│   ├── 5-done.md            ← 5-done：归档 + 写记忆
+│   ├── X-strategy.md        ← 横向：产品策略锚点（STRATEGY.md 创建/更新）
+│   ├── X-code-simplifier.md ← 横向：代码简化（基于 code-simplifier skill）
+│   ├── X-test-plan.md       ← 横向：自测计划生成（文档 + 集成测试代码）
+│   ├── X-compound.md        ← 横向：知识沉淀（docs/solutions/ + CONCEPTS.md）
+│   ├── X-review.md          ← 横向：代码级 review（blast radius + 风险评分 + 测试缺口）
+│   ├── X-health.md          ← 横向：项目健康巡检
+│   └── X-context-scan.md    ← 横向：首次入场扫描，生成项目全景
+│   ├── X-learn.md            ← 横向：self-learning 桥接（session→golden path→skill）
+│   ├── X-commit.md           ← 横向：Git Commit Message 生成
+│   ├── X-add-command.md      ← 横向：新增 atd 命令
+│   ├── X-table2xlsx.md       ← 横向：DDL→Excel 模板
+│   ├── X-xlsx2sql-insert.md  ← 横向：Excel→INSERT SQL
+│   ├── X-xlsx2sql-update.md  ← 横向：Excel→UPDATE SQL
+│   ├── X-travel-planner.md   ← 横向：旅行规划助手
+│   └── X-add-to-hc.md        ← 横向：添加 API 到 .hc 测试
+├── reference/
+│   ├── guards.md            ← R1-R6 硬性拦截规则 + B5 沿用抽象
+│   ├── gates.md             ← Gate 1-4 质量门禁详细规则
+│   ├── tdd.md               ← TDD 约束（红/绿/重构循环）
+│   ├── memory.md            ← 跨 session 记忆协议
+│   ├── learn.md             ← self-learning → atd 桥接协议
+│   ├── diagnose-loop.md     ← 结构化调试循环
+│   ├── risk.md              ← 风险评分算法
+│   └── git-guardrails.md    ← Git 安全防护
+└── templates/
+    ├── proposal.md          ← change 提案模板
+    ├── design.md            ← 技术设计模板
+    ├── tasks.md             ← 任务清单模板
+    ├── strategy.md          ← 产品策略模板（STRATEGY.md）
+    ├── solution.md          ← 知识沉淀模板（docs/solutions/）
+    ├── concepts.md          ← 领域词汇表模板（CONCEPTS.md）
+    ├── changelog.md         ← 需求变更记录模板
+    ├── progress.json        ← 执行进度模板
+    ├── .phase-state.json    ← 阶段状态模板（runtime）
+    ├── adr.md               ← 架构决策记录模板
+    ├── handoff.md           ← 交接文档模板
+    └── learn-skill.md       ← self-learning 生成 skill 模板
+```

package/bin/add-command.py

@@ -0,0 +1,144 @@
+#!/usr/bin/env python3
+"""
+atdc 命令生成器 — 一键创建跨 4 端的新命令
+
+用法:
+  python3 add-command.py <name> <desc> <trigger_words> [--prompt X-xxx]
+
+示例:
+  python3 add-command.py my-cmd "我的命令描述" "my-cmd、我的命令"
+  python3 add-command.py table2xlsx "DDL→Excel" "table2xlsx、生成模板" --prompt X-table2xlsx
+"""
+
+import os, sys, argparse
+
+ATD = os.path.expanduser("~/atdc")
+
+TEMPLATES = {
+    "opencode": """---
+description: {desc}，跳过自动路由
+---
+用 Read 工具读取 ${ATDC_DIR}/prompts/{prompt}.md，然后直接开始执行。
+
+$ARGUMENTS
+""",
+    "claude": """用 Read 工具读取 ${ATDC_DIR}/prompts/{prompt}.md，然后直接开始执行。
+跳过 GO.md 路由。
+
+$ARGUMENTS
+""",
+    "codex": """---
+name: atd:{name}
+description: {desc}。触发词：{triggers}。
+---
+用 Read 工具读取 `${ATDC_DIR}/prompts/{prompt}.md`，然后直接开始执行。
+""",
+    "cursor": """---
+name: atd:{name}
+description: {desc}。触发词：{triggers}。
+---
+用 Read 工具读取 `${ATDC_DIR}/prompts/{prompt}.md`，然后直接开始执行。
+""",
+}
+
+PATHS = {
+    "opencode": f"{ATD}/commands/opencode/atd/{{name}}.md",
+    "claude": f"{ATD}/commands/claude/atd/{{name}}.md",
+    "codex": f"{ATD}/commands/codex/atd-{{name}}/SKILL.md",
+    "cursor": f"{ATD}/commands/cursor/atd-{{name}}/SKILL.md",
+}
+
+def add_command(name, desc, triggers, prompt=None, short_desc=None, from_learn=False, failure=None, dead_end=None):
+    if prompt is None:
+        prompt = f"X-{name}"
+    if short_desc is None:
+        short_desc = desc[:30]
+
+    for platform, tmpl in TEMPLATES.items():
+        path = PATHS[platform].format(name=name)
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        content = tmpl.format(name=name, desc=desc, triggers=triggers,
+                              prompt=prompt, short_desc=short_desc)
+        with open(path, "w") as f:
+            f.write(content)
+        print(f"  ✓ {platform:10s} {path}")
+
+    # create prompt template
+    prompt_path = f"{ATD}/prompts/{prompt}.md"
+    if not os.path.exists(prompt_path):
+        os.makedirs(os.path.dirname(prompt_path), exist_ok=True)
+        if from_learn:
+            with open(prompt_path, "w") as f:
+                f.write(f"# prompts/{prompt} · {short_desc}\n\n")
+                f.write(f"横向命令，任意时刻可触发：`/atdc:{name} <args>`\n\n")
+                f.write(f"> 🧠 Auto-harvested by self-learning\n\n")
+                f.write("---\n\n")
+                if failure:
+                    f.write(f"## 失败模式\n\n")
+                    f.write(f"**这个 skill 避免的诊断**：`{failure}`\n\n")
+                f.write("## 执行步骤\n\n")
+                f.write("### 1. 确定输入\n\n")
+                f.write("### 2. 执行\n\n")
+                f.write("---\n\n")
+                if dead_end:
+                    f.write(f"## What didn't work\n\n")
+                    f.write(f"- `{dead_end}`：被排除\n\n")
+                f.write("## 验证方式\n\n")
+                f.write("`<passing check — 什么命令/测试验证了这个路径>`\n\n")
+        else:
+            with open(prompt_path, "w") as f:
+                f.write(f"# prompts/{prompt} · {short_desc}\n\n")
+                f.write(f"横向命令，任意时刻可触发：`/atdc:{name} <args>`\n\n")
+                f.write("## 执行步骤\n\n")
+                f.write("### 1. 确定输入\n\n")
+                f.write("### 2. 执行\n\n")
+        print(f"  ✓ prompt    {prompt_path}")
+
+    # update install.sh skill list
+    install_sh = f"{ATD}/install.sh"
+    with open(install_sh) as f:
+        content = f.read()
+
+    skill_name = f"atd-{name}"
+    marker = "for skill in atd "
+    if marker in content and skill_name not in content:
+        # Find the "for skill in" line and add the new skill
+        lines = content.split("\n")
+        for i, line in enumerate(lines):
+            if "for skill in atd " in line and skill_name not in line:
+                # Insert before the "do" keyword
+                j = line.rfind("; do")
+                if j < 0:
+                    continue
+                lines[i] = line[:j] + f" {skill_name}" + line[j:]
+                break
+        with open(install_sh, "w") as f:
+            f.write("\n".join(lines))
+        print(f"  ✓ install.sh {skill_name} 已注册")
+    else:
+        print(f"  - install.sh {skill_name} 已存在或无需更新")
+
+    # create agents/skills symlink
+    agents_skill = os.path.expanduser(f"~/.agents/skills/{skill_name}")
+    target = f"{ATD}/commands/codex/{skill_name}"
+    if not os.path.islink(agents_skill):
+        os.symlink(target, agents_skill)
+        print(f"  ✓ symlink   {agents_skill} -> {target}")
+
+    print(f"\n✅ 命令 /atdc:{name} 已创建（4 端 + prompt + install.sh + symlink）")
+    print(f"   重启各终端 Ctrl+C 重进即可使用。")
+
+
+if __name__ == "__main__":
+    p = argparse.ArgumentParser(description="atdc 命令生成器")
+    p.add_argument("name", help="命令名 (kebab-case, 如 my-cmd)")
+    p.add_argument("desc", help="命令描述")
+    p.add_argument("triggers", help="触发词 (逗号分隔, 如 'cmd、命令')")
+    p.add_argument("--prompt", help="prompt 文件名 (默认 X-<name>)")
+    p.add_argument("--short", help="简短描述 (body 结尾句)")
+    p.add_argument("--from-learn", action="store_true", help="从 self-learning harvest 生成（使用 learn-skill 模板）")
+    p.add_argument("--failure", help="这个 skill 避免/诊断的失败模式")
+    p.add_argument("--dead-end", help="被排除的死路方案")
+    args = p.parse_args()
+    add_command(args.name, args.desc, args.triggers, args.prompt, args.short,
+                from_learn=args.from_learn, failure=args.failure, dead_end=args.dead_end)