@kunlv/atdc 1.0.0

package/packages/cls/src/client.js

@@ -0,0 +1,262 @@
+const fs = require('fs');
+const path = require('path');
+const crypto = require('crypto');
+const os = require('os');
+const { execSync, exec } = require('child_process');
+
+const CONFIG_DIR = path.join(os.homedir(), '.cls');
+const CONFIG_FILE = path.join(CONFIG_DIR, 'config.json');
+const CREDS_FILE = path.join(CONFIG_DIR, 'credentials.json');
+const DEFAULT_TEMPLATE = path.join(__dirname, '..', 'config', 'defaults.json');
+
+function _defaults() {
+  return {
+    skill_dir: '',
+    python: 'python3',
+    accounts: {},
+    defaults: { limit: 200, out_dir: '.', topic_type: 'error', regions: 'gz,bj', time_range: '15m' },
+    output: { format: 'jsonl', filename: '{account}_{query}_{ts}-{suffix}.jsonl' },
+  };
+}
+
+function initConfig() {
+  fs.mkdirSync(CONFIG_DIR, { recursive: true });
+  if (fs.existsSync(CONFIG_FILE)) {
+    return { ok: false, msg: `配置文件已存在: ${CONFIG_FILE}`, path: CONFIG_FILE };
+  }
+  if (!fs.existsSync(DEFAULT_TEMPLATE)) {
+    return { ok: false, msg: `模板文件不存在: ${DEFAULT_TEMPLATE}` };
+  }
+  const template = fs.readFileSync(DEFAULT_TEMPLATE, 'utf8');
+  fs.writeFileSync(CONFIG_FILE, template);
+  return { ok: true, msg: `配置文件已生成: ${CONFIG_FILE}，请编辑 skill_dir 和 accounts`, path: CONFIG_FILE };
+}
+
+function loadConfig() {
+  if (!fs.existsSync(CONFIG_FILE)) {
+    throw new Error(`配置文件 ${CONFIG_FILE} 不存在。请运行: cls --init`);
+  }
+  const raw = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+  return { ..._defaults(), ...raw, defaults: { ..._defaults().defaults, ...(raw.defaults || {}) }, output: { ..._defaults().output, ...(raw.output || {}) } };
+}
+
+function resolveAccount(config, alias) {
+  const entry = config.accounts[alias];
+  if (!entry) {
+    const available = Object.keys(config.accounts).join(', ');
+    throw new Error(`账号 "${alias}" 未在配置中找到。可用: ${available}`);
+  }
+  if (typeof entry === 'string') return { account: entry, project_id: null };
+  return { account: entry.account || alias, project_id: entry.project_id || null };
+}
+
+function detectPython(cmd) {
+  try {
+    execSync(`which "${cmd}" 2>/dev/null || command -v "${cmd}"`, { encoding: 'utf8' });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function _relativeTime(range) {
+  const m = range.match(/^(\d+)(m|h|d|s)$/);
+  if (!m) throw new Error(`无效的时间范围: ${range}（支持 15m/1h/2d）`);
+  const val = parseInt(m[1]);
+  const unit = m[2];
+  const ms = val * { s: 1000, m: 60000, h: 3600000, d: 86400000 }[unit];
+  return new Date(Date.now() - ms).toISOString().replace('T', ' ').slice(0, 19);
+}
+
+function _now() {
+  return new Date().toISOString().replace('T', ' ').slice(0, 19);
+}
+
+function _safeQuery(query) {
+  return (query || 'log')
+    .replace(/[^a-zA-Z0-9\u4e00-\u9fff]+/g, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_|_$/g, '')
+    .slice(0, 30);
+}
+
+function buildOutputPath(account, query, outDir) {
+  const ts = new Date().toISOString().replace(/[-:T]/g, '').slice(0, 15);
+  const suffix = crypto.randomBytes(2).toString('hex');
+  const safeQ = _safeQuery(query);
+  const ext = 'jsonl';
+  const name = `${account}_${safeQ}_${ts}-${suffix}.${ext}`;
+  const dir = (outDir || '.').replace(/^~/, os.homedir());
+  fs.mkdirSync(dir, { recursive: true });
+  return path.join(dir, name);
+}
+
+function buildSearchArgs(config, account, query, opts = {}) {
+  const resolved = resolveAccount(config, account);
+  const script = path.join(config.skill_dir, 'scripts', 'cls_query_python.py');
+  const outputPath = buildOutputPath(account, query, opts.out_dir || config.defaults.out_dir);
+  const limit = opts.limit || config.defaults.limit;
+  const from = opts.from || _relativeTime(config.defaults.time_range);
+  const to = opts.to || _now();
+  const topicType = opts.type || config.defaults.topic_type;
+  const regions = opts.regions || config.defaults.regions;
+
+  const args = [
+    config.python,
+    script,
+    '--query', query,
+    '--limit', String(limit),
+    '--from', from,
+    '--to', to,
+    '--topic-type', topicType,
+    '--regions', regions,
+    '--output', outputPath,
+    '--pretty',
+  ];
+
+  // credentials from ~/.cls/credentials.json (if exists)
+  if (fs.existsSync(CREDS_FILE)) {
+    const creds = JSON.parse(fs.readFileSync(CREDS_FILE, 'utf8'));
+    const cred = creds[resolved.account];
+    if (cred && cred.secret_id && cred.secret_key) {
+      args.push('--secret-id', cred.secret_id, '--secret-key', cred.secret_key);
+    }
+  }
+  // fallback: --account for inventory + credentials routing
+  args.push('--account', resolved.account);
+
+  if (resolved.project_id) {
+    args.push('--project-id', resolved.project_id);
+  }
+
+  return { args, outputPath };
+}
+
+function buildFetchArgs(config, account, query, opts = {}) {
+  const resolved = resolveAccount(config, account);
+  const script = path.join(config.skill_dir, 'scripts', 'cls_fetch_bulk.py');
+  const outputPath = buildOutputPath(account, query, opts.out_dir || config.defaults.out_dir);
+  const from = opts.from || _relativeTime(config.defaults.time_range);
+  const to = opts.to || _now();
+  const max = opts.max || 5000;
+
+  const args = [
+    config.python,
+    script,
+    '--query', query,
+    '--from', from,
+    '--to', to,
+    '--max', String(max),
+    '--out', outputPath,
+    '--content-only',
+  ];
+
+  if (fs.existsSync(CREDS_FILE)) {
+    const creds = JSON.parse(fs.readFileSync(CREDS_FILE, 'utf8'));
+    const cred = creds[resolved.account];
+    if (cred && cred.secret_id && cred.secret_key) {
+      args.push('--secret-id', cred.secret_id, '--secret-key', cred.secret_key);
+    }
+  }
+  args.push('--account', resolved.account);
+  if (resolved.project_id) {
+    args.push('--project-id', resolved.project_id);
+  }
+
+  return { args, outputPath };
+}
+
+function listAccounts() {
+  const config = loadConfig();
+  const result = {};
+  for (const [alias, entry] of Object.entries(config.accounts)) {
+    if (typeof entry === 'string') {
+      result[alias] = entry;
+    } else {
+      result[alias] = `${entry.account} → project ${entry.project_id}`;
+    }
+  }
+  return result;
+}
+
+function searchSync(account, query, opts = {}) {
+  const config = loadConfig();
+  if (!detectPython(config.python)) throw new Error(`Python 解释器 "${config.python}" 未找到。请检查 ~/.cls/config.json 中 python 字段`);
+
+  const { args, outputPath } = buildSearchArgs(config, account, query, opts);
+  const cmd = args.map(a => a.includes(' ') ? `"${a}"` : a).join(' ');
+
+  if (!opts.quiet) console.error(`→ ${cmd}`);
+
+  execSync(cmd, { encoding: 'utf8', maxBuffer: 50 * 1024 * 1024, timeout: (opts.timeout || 60) * 1000 });
+  const raw = fs.readFileSync(outputPath, 'utf8');
+  const data = JSON.parse(raw);
+  const count = data?.Response?.Results?.length || data?.summary?.returned_count || 0;
+
+  return { output_file: outputPath, count, sample: (data?.Response?.Results || []).slice(0, 3) };
+}
+
+function searchAsync(account, query, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const config = loadConfig();
+    if (!detectPython(config.python)) return reject(new Error(`Python "${config.python}" 未找到`));
+
+    const { args, outputPath } = buildSearchArgs(config, account, query, opts);
+    const cmd = args.map(a => a.includes(' ') ? `"${a}"` : a).join(' ');
+
+    exec(cmd, { encoding: 'utf8', maxBuffer: 50 * 1024 * 1024, timeout: (opts.timeout || 60) * 1000 }, (err, stdout, stderr) => {
+      if (err) return reject(new Error(stderr || err.message));
+      try {
+        const raw = fs.readFileSync(outputPath, 'utf8');
+        const data = JSON.parse(raw);
+        const count = data?.Response?.Results?.length || data?.summary?.returned_count || 0;
+        resolve({ output_file: outputPath, count, sample: (data?.Response?.Results || []).slice(0, 3) });
+      } catch (e) {
+        reject(e);
+      }
+    });
+  });
+}
+
+function fetchSync(account, query, opts = {}) {
+  const config = loadConfig();
+  if (!detectPython(config.python)) throw new Error(`Python "${config.python}" 未找到`);
+
+  const { args, outputPath } = buildFetchArgs(config, account, query, opts);
+  const cmd = args.map(a => a.includes(' ') ? `"${a}"` : a).join(' ');
+
+  if (!opts.quiet) console.error(`→ ${cmd}`);
+
+  execSync(cmd, { encoding: 'utf8', maxBuffer: 200 * 1024 * 1024, timeout: (opts.timeout || 120) * 1000 });
+  const lines = fs.readFileSync(outputPath, 'utf8').split('\n').filter(Boolean);
+  return { output_file: outputPath, total: lines.length };
+}
+
+function fetchAsync(account, query, opts = {}) {
+  return new Promise((resolve, reject) => {
+    const config = loadConfig();
+    if (!detectPython(config.python)) return reject(new Error(`Python "${config.python}" 未找到`));
+
+    const { args, outputPath } = buildFetchArgs(config, account, query, opts);
+    const cmd = args.map(a => a.includes(' ') ? `"${a}"` : a).join(' ');
+
+    exec(cmd, { encoding: 'utf8', maxBuffer: 200 * 1024 * 1024, timeout: (opts.timeout || 120) * 1000 }, (err, stdout, stderr) => {
+      if (err) return reject(new Error(stderr || err.message));
+      const lines = fs.readFileSync(outputPath, 'utf8').split('\n').filter(Boolean);
+      resolve({ output_file: outputPath, total: lines.length });
+    });
+  });
+}
+
+module.exports = {
+  initConfig,
+  loadConfig,
+  detectPython,
+  resolveAccount,
+  listAccounts,
+  searchSync,
+  searchAsync,
+  fetchSync,
+  fetchAsync,
+  buildOutputPath,
+};

package/prompts/1-spec.md

@@ -0,0 +1,271 @@
+# prompts/1-spec · 需求澄清 + 规格生成
+
+从此文件读取后，直接开始执行，无需用户再次确认启动。
+
+---
+
+## 🔴 Step -1：规则加载（Phase 3 到达时必须执行）
+
+> 1-spec 的 Phase 0-2 不依赖外部规则，可直接执行。
+> 到达 Phase 3（复杂度评估）时，MUST Read 以下文件：
+
+```
+Read @atdc/reference/risk.md → 风险评分算法 + blast radius 评估规则
+```
+
+---
+
+## Phase 0：判断模式
+
+### 0a. 读取产品策略（存在时自动注入）
+
+```bash
+cat STRATEGY.md 2>/dev/null || echo "[无 STRATEGY.md]"
+```
+
+如果 STRATEGY.md 存在，将其作为 **方向约束** 注入后续所有 Phase：
+- Phase 1 的提问要对照策略中的 Target Problem、Persona、Key Metrics
+- Phase 2 的 proposal 要体现策略中的 Approach 和 Tracks
+- 如果需求与 STRATEGY.md 的 Out of Scope 冲突，主动提示用户
+
+不存在则跳过，不影响正常流程。
+
+### 0b. 判断需求清晰度
+
+检查用户输入是否模糊（"我想…"/"有个想法"/"brainstorm" 等）：
+
+- **模糊** → 先执行 Phase 1（需求澄清）再到 Phase 2
+- **明确需求** → 跳过 Phase 1，直接从 Phase 2 开始
+
+---
+
+## Phase 1：需求澄清（Brainstorm 模式）
+
+逐一提问，每次只问一个问题，等用户回答后再问下一个：
+
+1. 这个功能/改动是给谁用的？核心使用场景是什么？
+2. 成功的标准是什么？用户做了什么操作、看到什么结果算完成？
+3. 有哪些不能动的模块、性能要求或兼容性约束？
+4. 有没有已经排除的方案？（避免重蹈）
+
+问完后，提出 2-3 个技术方案 + 推荐理由，等用户选定后继续。
+
+### Phase 1.5：UI v0 草稿（仅涉及新页面/新组件时触发）
+
+确认本次变更涉及 UI 视觉层后，输出 v0 草稿供确认：
+
+```
+📌 UI v0 草稿（30 秒扫完，方向对了就继续）：
+- 调性：<一个词>
+- 主色：<颜色描述>
+- 字体：display = <字体> / body = <字体>
+- 缩略布局：
+  ┌─────────────────┐
+  │   [示意]        │
+  └─────────────────┘
+
+我正在假设：
+- 假设 <A>
+- 假设 <B>
+
+继续还是调整哪个维度？
+```
+
+用户确认后才继续。局部调整只改对应维度，不重写全部。
+
+---
+
+## Phase 1→2 过渡：文档输出提醒
+
+> **💡 省钱提示**：接下来将生成 proposal.md + design.md + specs/ + tasks.md，预计输出 5-15K token。
+> 如果当前使用昂贵模型，建议切到便宜模型（如 glm-4-flash）后再继续。
+> 完成后切回即可。
+>
+> **模式 C（可选）**：如果你决定切模型，现在暂停，用 `/model <便宜模型>` 切换后回复"继续"。
+> 不切模型则直接进入 Phase 2。
+
+---
+
+## Phase 2：生成 change 目录
+
+```bash
+# 根据需求生成 change 名称（kebab-case，英文，描述功能）
+CHANGE_NAME="<name>"
+mkdir -p openspec/changes/$CHANGE_NAME/specs
+
+# 🔴 初始化状态文件（触发 evidence PostToolUse hook）
+cat > openspec/changes/$CHANGE_NAME/.phase-state.json << 'STATE'
+{
+  "change": "<name>",
+  "phase": "open",
+  "mode": "full",
+  "tasks": { "total": 0, "completed": 0 },
+  "verifiedAt": null,
+  "archived": false
+}
+STATE
+# PostToolUse hook 检测到写入后自动记录 phase_transition(init→open) 事件
+```
+
+生成以下文件：
+
+### 2a. proposal.md
+
+参考 `@atdc/templates/proposal.md`，填充：
+- **背景与目标**：一句话（对谁/做什么/达到什么效果）
+- **技术方案**：选定方案 + 核心理由
+- **排除的方案**：被否定的选项及原因
+- **实施范围**：涉及模块、文件列表、接口变更
+
+### 2b. design.md
+
+参考 `@atdc/templates/design.md`，填充：
+- 模块划分与职责
+- 关键接口定义（函数签名/API 路由）
+- 数据流说明
+- 关键决策与 ADR
+
+### 2c. specs/<模块名>/spec.md
+
+每个涉及模块一个 spec 文件（放在 `openspec/changes/<name>/specs/<模块名>/spec.md`），包含：
+- 每条需求使用 `SHALL` 或 `MUST`（禁止用 should/might/可能）
+- 每个场景有 Given/When/Then 或可量化预期结果
+- 覆盖 happy path + sad path
+- 覆盖边界场景（空值/超限/并发/降级）
+
+### 2d. tasks.md
+
+参考 `@atdc/templates/tasks.md`，每个任务格式：
+
+```markdown
+### N. <任务标题>
+
+**目标**: <一句话说明完成后达到什么状态>
+**Files**: [path/to/file1.go, path/to/file2.go]
+**Dependencies**: <依赖的任务编号，或 none>
+**估时**: <8-15 分钟>
+
+实现步骤：
+1. ...
+2. ...
+
+验证方式：
+- [ ] <具体可执行的验证命令或检查项>
+```
+
+任务颗粒度：每个任务 8-15 分钟可完成，可并行的任务标注 `Dependencies: none`。
+
+### 2e. Verification Checklist
+
+在 tasks.md 末尾生成：
+
+```markdown
+## Verification Checklist
+
+从 `openspec/changes/<name>/specs/` 提取所有 SHALL/MUST，逐条列出：
+- [ ] 系统 SHALL <需求描述> → Task N
+- [ ] 系统 MUST <需求描述> → Task N
+```
+
+---
+
+## Phase 3：复杂度评估 + C1 暂停
+
+### 3a. 自动评估复杂度
+
+tasks.md 生成完成后，统计以下维度：
+
+| 维度 | 简单 | 复杂 |
+|------|------|------|
+| 任务数 | ≤ 4 | > 4 |
+| 涉及模块数 | 1 | > 1 |
+| 跨层改动 | 无（纯逻辑/工具函数） | 有（接口变更、DB、缓存、路由） |
+| 任务间依赖 | Dependencies: none 居多 | 有依赖链（Task N → Task M） |
+| 破坏性变更 | 无 | 有（改公共函数签名、删接口） |
+
+### 3a-α. 预估 Blast Radius（可选但有条件触发）
+
+当 Phase 3a 命中 ≥2 条复杂维度时，**自动执行预估影响分析**：
+
+对 design.md 中"涉及文件"声明的关键符号，运行：
+```
+codegraph_impact "<SymbolName>" depth=1
+```
+
+将影响深度纳入复杂度评估：
+
+| 预估影响 | 额外复杂度加分 |
+|---------|-------------|
+| blast radius ≤3 个调用方，单模块 | +0 |
+| blast radius 4-10 个，跨 2 个模块 | +1 维度 |
+| blast radius >10 个，跨 ≥3 个模块 | +2 维度 |
+
+参考 `@atdc/reference/risk.md` 的快速评估规则。
+
+**命中 2 条及以上 → 复杂，强制 grill**：直接读取 `@atdc/prompts/2-qa.md` 执行，grill 完成并用户确认后再暂停等待 C1。
+
+**命中 0-1 条 → 简单**：直接暂停等待 C1，提示用户可选 grill。
+
+### 3b. 输出 C1 暂停信息
+
+**复杂（强制 grill 后）：**
+
+```
+📋 规格生成完成，已完成 Grill 质疑检验，等待 C1 审核：
+
+变更目录：openspec/changes/<name>/
+├── proposal.md   ✓
+├── design.md     ✓
+├── tasks.md      ✓（N 个任务）
+└── specs/        ✓（N 个模块）
+
+复杂度评估：命中 <N> 条复杂维度，已强制执行 Grill。
+
+审核重点：
+1. 需求完整、无歧义（openspec/changes/<name>/specs/ 中无 should/might）
+2. 技术方案可行（design.md 接口定义合理）
+3. 任务粒度合适（每个 8-15 分钟）
+4. Verification Checklist 覆盖所有 SHALL/MUST
+5. Grill 报告中的严重问题已处理
+
+审核通过后说"执行"或"run"，AI 必须读取 `atdc/prompts/3-impl.md` 进入执行阶段，禁止直接写代码。
+```
+
+**简单（可选 grill）：**
+
+```
+📋 规格生成完成，等待 C1 审核：
+
+变更目录：openspec/changes/<name>/
+├── proposal.md   ✓
+├── design.md     ✓
+├── tasks.md      ✓（N 个任务）
+└── specs/        ✓（N 个模块）
+
+审核重点：
+1. 需求完整、无歧义（openspec/changes/<name>/specs/ 中无 should/might）
+2. 技术方案可行（design.md 接口定义合理）
+3. 任务粒度合适（每个 8-15 分钟）
+4. Verification Checklist 覆盖所有 SHALL/MUST
+
+审核通过后说"执行"或"run"，AI 必须读取 `atdc/prompts/3-impl.md` 进入执行阶段，禁止直接写代码。
+如需在执行前做一轮质疑检验，说"grill"。
+```
+
+---
+
+## Phase 3（可选）：深度拷问 + 文档沉淀
+
+提案生成后，可用 `/atdc:grill-with-docs` 进行更深层的拷问，
+与 2-qa 的区别：2-qa 重在找漏洞，grill-with-docs 重在建立共享语言并持久化。
+
+> 💡 是否需要对方案进行深度拷问？
+> - 说 `grill-docs` → 执行 `/atdc:grill-with-docs`：
+>   1. 对照 CONTEXT.md 和现有 ADR 挑战方案假设
+>   2. 更新 CONTEXT.md（领域术语、模块边界）
+>   3. 重大决策生成 ADR（`docs/adr/<序号>-<标题>.md`）
+> - 说 `继续` 或直接描述下一步 → 跳过，进入 C1 审核
+
+> **触发条件**：仅当 CONTEXT.md 已存在时显示此提示，否则跳过 Phase 3。
+
+**不得在用户确认前开始写任何代码。**