@cat-kit/agent-context 1.0.7 → 1.1.1

package/src/content/actions.ts

@@ -0,0 +1,238 @@
+export const ACTION_NAMES = ['init', 'plan', 'replan', 'implement', 'patch', 'rush'] as const
+type ActionName = (typeof ACTION_NAMES)[number]
+
+export const ACTION_RENDERERS: Record<ActionName, () => string> = {
+  init: renderInit,
+  plan: renderPlan,
+  replan: renderReplan,
+  implement: renderImplement,
+  patch: renderPatch,
+  rush: renderRush
+}
+
+function renderInit(): string {
+  return `# init
+
+初始化项目的 Agent Context 上下文。根据新旧项目类型处理 \`AGENTS.md\`，新项目会自动进入计划创建流程。
+
+可附带描述参数，用于补充项目背景、技术栈、特殊约束。
+
+## 执行步骤
+
+1. **判断项目类型**：检测根目录是否存在有效代码文件和目录结构。
+   - 新项目：无实质代码，或用户明确说明是新项目。
+   - 旧项目：已有代码、配置文件和目录结构。
+   - 无法判断 → 向用户提问澄清，不可假设。
+
+2. **处理 AGENTS.md**：
+   - 新项目：
+     1. 通过提问澄清以下要点（已从描述中获取的可跳过）：项目目标与核心功能、技术栈与版本、代码规范与工具链（lint/formatter/测试）、目录结构偏好。
+     2. 生成高质量 \`AGENTS.md\`（须满足下方质量标准，不满足则重新优化直至满足）。
+     3. 继续执行 plan 创建初始计划。
+   - 旧项目：
+     1. 若不存在 \`AGENTS.md\`：通过提问与代码阅读收集信息后生成。
+     2. 若已存在 \`AGENTS.md\`：按质量标准评估，不足时增补优化。
+     3. 默认不创建计划（除非用户明确要求）。
+
+3. **输出反馈**：向用户报告项目类型判定结果、AGENTS.md 处理结果、是否需要后续计划。
+
+## 高质量 AGENTS.md 标准
+
+- 常用命令与约束前置，降低代理执行歧义。
+- 明确列出目录结构（至少到第二层）。
+- 明确标注技术栈及版本。
+- 明确代码风格约束（命名规范、格式化工具、lint 配置）。
+- 内容精简，无冗余段落或模板化填充。
+- 大型单体仓库按子包拆分维护本地 \`AGENTS.md\`。
+`
+}
+
+function renderPlan(): string {
+  return `# plan
+
+创建新的执行计划，写入 \`.agent-context/plan-{number}/plan.md\`。按复杂度可拆分为多个计划，维护「单当前计划 + preparing 队列」结构。
+
+必须附带计划描述。
+
+## 前置检查
+
+- 运行 \`agent-context validate\`，不通过则中止并报告错误。
+- 描述为空 → 拒绝执行。
+- 存在未归档的已执行当前计划 → 拒绝执行，提示先运行 \`agent-context done\` 归档。
+- 存在多个当前计划 → 拒绝执行，提示恢复单活跃状态。
+
+## 执行步骤
+
+1. **需求澄清**（存在以下任一歧义时必须提问，否则跳到步骤 2）：
+   - 范围边界不清：无法判定影响哪些文件或模块。
+   - 存在显著不同的技术路径需用户决策。
+   - 验收标准不明确：无法判断何时算"完成"。
+2. 按复杂度决定单计划或多计划拆分。
+3. 多计划拆分时：最小编号进入 \`.agent-context/\` 作为当前计划，其余进入 \`.agent-context/preparing/\`。单计划直接创建。
+4. 每个计划创建 \`plan.md\`，遵循下方模板。
+5. **自检**（不通过则修改后重新检查）：
+   - 每个步骤可独立执行且有明确完成标准。
+   - 不存在过度拆分或拆分不足。
+   - 影响范围可预估。
+
+## plan.md 模板
+
+\`\`\`markdown
+# {计划名称}
+
+> 状态: 未执行
+
+## 目标
+
+{明确的目标描述}
+
+## 内容
+
+{详细的实施步骤}
+
+## 影响范围
+
+## 历史补丁
+\`\`\`
+
+- 状态行唯一，仅允许 \`未执行\` 或 \`已执行\`。
+- \`## 目标\` 与 \`## 内容\` 不可为空。
+- \`## 影响范围\` 与 \`## 历史补丁\` 创建时留空，后续由 implement 和 patch 写入。
+`
+}
+
+function renderReplan(): string {
+  return `# replan
+
+重新规划已有的未实施计划，保持「单当前计划 + preparing 队列」结构不变。
+
+必须附带重规划描述。
+
+## 前置检查
+
+- 运行 \`agent-context validate\`，不通过则中止并报告错误。
+- 描述为空 → 拒绝执行。
+- 无未实施计划 → 拒绝执行，提示使用 plan 创建。
+- 存在多个当前计划 → 拒绝执行，提示恢复单活跃状态。
+- 目标计划编号不存在 → 拒绝执行，列出可选编号。
+- 目标计划已执行 → 拒绝执行，提示使用 patch。
+
+## 作用域
+
+- 默认作用域：\`.agent-context/preparing/\` 中全部未实施计划。
+- 可通过描述指定仅重规划部分计划（如"重规划 plan-3 和 plan-5"）。
+- 当前计划为 \`已执行\` → 禁止重写，仅允许重规划 \`preparing/\` 队列。
+- 当前计划为 \`未执行\` 且用户明确要求 → 可纳入重规划范围。
+
+## 执行步骤
+
+1. 解析描述，确定重规划目标范围。
+2. 读取目标计划 \`plan.md\`，理解现有意图。
+3. 生成新的拆分方案，保持「单当前计划 + 若干 preparing 计划」结构。
+4. 新增计划编号：全局 max(N)+1 递增分配；未改动计划保持原编号。
+5. 更新目录结构，确保每个新计划的 \`plan.md\` 遵循标准模板。
+`
+}
+
+function renderImplement(): string {
+  return `# implement
+
+实施当前计划 \`.agent-context/plan-{number}/plan.md\` 中的全部步骤，通过验证循环后将状态更新为「已执行」。
+
+不接受额外描述。
+
+## 前置检查
+
+- 运行 \`agent-context validate\`，不通过则中止并报告错误。
+- 带描述 → 拒绝执行。
+- 当前计划不存在 → 拒绝执行，提示先创建计划。
+- 当前计划状态为 \`已执行\` → 拒绝执行，提示使用 patch 修补或运行 \`agent-context done\` 归档。
+- \`## 目标\` 或 \`## 内容\` 为空 → 拒绝执行，提示补充。
+- 存在多个当前计划 → 拒绝执行，提示恢复单活跃状态。
+- 仅操作当前计划，不直接操作 \`preparing/\` 中的计划。
+- 遇到阻塞问题应向用户报告，不可静默跳过。
+
+## 执行步骤
+
+1. 读取当前计划 \`plan.md\`，理解 \`## 目标\` 与 \`## 内容\`。
+2. 依据 \`## 内容\` 中的步骤逐项实施。
+3. **验证循环**（全部通过前不可进入步骤 4）：
+   a. 逐项对照 \`## 内容\` 确认每个步骤已实施。
+   b. 运行项目验证：类型检查 → lint → 测试。
+   c. 若存在失败项 → 修复后回到 a 重新验证。
+   d. 全部通过 → 进入步骤 4。
+4. 更新 \`plan.md\` 状态行：\`> 状态: 未执行\` → \`> 状态: 已执行\`。
+5. 更新 \`## 影响范围\`，记录所有变更文件。
+`
+}
+
+function renderPatch(): string {
+  return `# patch
+
+基于当前已执行计划创建增量补丁，修复问题或追加变更。
+
+必须附带补丁描述。
+
+## 前置检查
+
+- 运行 \`agent-context validate\`，不通过则中止并报告错误。
+- 描述为空 → 拒绝执行。
+- 当前计划不存在 → 拒绝执行，提示先创建计划。
+- 当前计划状态为 \`未执行\` → 拒绝执行，提示先实施。
+- 存在多个当前计划 → 拒绝执行，提示恢复单活跃状态。
+- 补丁不改变计划状态，完成后保持 \`已执行\`。
+
+## 执行步骤
+
+1. 阅读 \`plan.md\` 与已有 \`patch-{number}.md\`，了解上下文与历史，避免重复修复。
+2. 根据描述执行补丁所需的代码变更。
+3. 完成必要验证（测试、类型检查等）。
+4. 创建 \`patch-{number}.md\`（编号：扫描当前计划目录已有补丁取 max+1），遵循下方模板。
+5. 回写 \`plan.md\`：
+   - \`## 历史补丁\`：追加 \`- patch-{number}: {补丁名称}\`，按编号去重。
+   - \`## 影响范围\`：合并本次变更路径，按路径去重。
+
+## patch.md 模板
+
+\`\`\`markdown
+# {补丁名称}
+
+## 补丁内容
+
+{修改了什么、为什么修改}
+
+## 影响范围
+
+- 新增文件: \`/path/to/file\`
+- 修改文件: \`/path/to/file\`
+- 删除文件: \`/path/to/file\`
+\`\`\`
+`
+}
+
+function renderRush(): string {
+  return `# rush
+
+快速通道：创建计划并立即实施，适合范围明确、无需多轮规划的任务。
+
+必须附带任务描述。
+
+## 前置检查
+
+- 运行 \`agent-context validate\`，不通过则中止并报告错误。
+- 描述为空 → 拒绝执行。
+- 存在未归档的已执行当前计划 → 拒绝执行，提示先运行 \`agent-context done\` 归档。
+- 存在未实施的当前计划 → 拒绝执行，提示先 implement 或 replan。
+
+## 执行步骤
+
+1. 按 plan 协议创建单计划（不拆分，不进入 preparing 队列）。
+2. 无需用户确认计划内容，直接进入 implement 流程。
+3. 按 implement 协议执行全部步骤，包括验证循环：
+   a. 逐项对照 \`## 内容\` 确认每个步骤已实施。
+   b. 运行项目验证：类型检查 → lint → 测试。
+   c. 若存在失败项 → 修复后重新验证。
+   d. 全部通过 → 进入步骤 4。
+4. 更新 \`plan.md\` 状态行为 \`已执行\`，更新 \`## 影响范围\`。
+`
+}

package/src/content/index.ts

@@ -0,0 +1,94 @@
+import type { SkillArtifacts, ToolTarget } from '../types.js'
+import { ACTION_NAMES, ACTION_RENDERERS } from './actions.js'
+
+const SKILL_NAME = 'ac-workflow'
+const SKILL_DESCRIPTION =
+  '管理 .agent-context 计划生命周期，按 init、plan、replan、implement、patch、rush、done 协议推进任务。'
+
+export function renderSkillArtifacts(target: ToolTarget): SkillArtifacts {
+  const files: SkillArtifacts['files'] = [
+    { relativePath: 'SKILL.md', body: renderNavigator(target) },
+    ...ACTION_NAMES.map((name) => ({
+      relativePath: `actions/${name}.md`,
+      body: ACTION_RENDERERS[name]()
+    }))
+  ]
+
+  if (target.metadataFiles.includes('openai')) {
+    files.push({ relativePath: 'agents/openai.yaml', body: renderOpenAIMetadata() })
+  }
+
+  return { files }
+}
+
+// ── Navigator ────────────────────────────────────────
+
+function renderNavigator(target: ToolTarget): string {
+  return `${renderFrontmatter(target)}
+# Agent Context
+
+管理项目中的 \`.agent-context/\` 计划生命周期。匹配用户意图后，读取对应协议文件（相对于本文件所在目录）严格执行。
+
+## 意图匹配
+
+| 用户意图 | 动作 | 协议文件 |
+|----------|------|----------|
+| 初始化项目上下文、补全 AGENTS | init | \`actions/init.md\` |
+| 给需求出计划、拆分任务 | plan | \`actions/plan.md\` |
+| 重做计划、调整方案 | replan | \`actions/replan.md\` |
+| 按计划开始做、实现当前计划 | implement | \`actions/implement.md\` |
+| 补一个小改动、在当前结果上修 | patch | \`actions/patch.md\` |
+| 快速出计划并实施 | rush | \`actions/rush.md\` |
+| 任务彻底完成、归档当前计划 | done | 运行 \`agent-context done\` |
+
+## 全局约束
+
+- 状态机两态：\`未执行\`、\`已执行\`。
+- 任意时刻最多一个当前计划：\`.agent-context/plan-{number}\`。
+- 多个当前计划 → 拒绝执行，提示恢复单活跃状态。
+- 计划编号全局递增，不复用。补丁编号在单计划目录内递增，不复用。
+
+## 目录结构
+
+\`\`\`text
+.agent-context/
+├── plan-{N}/          # 当前计划（最多一个）
+│   ├── plan.md
+│   └── patch-{N}.md
+├── preparing/         # 待执行计划队列
+│   └── plan-{N}/
+└── done/              # 已归档计划
+    └── plan-{N}-{YYYYMMDD}/
+\`\`\`
+
+编号规则：扫描全部 \`plan-N\` 目录取 \`max(N)+1\`。
+`
+}
+
+// ── Frontmatter & Metadata ──────────────────────────
+
+function renderFrontmatter(target: ToolTarget): string {
+  const lines = ['---', `name: ${SKILL_NAME}`, `description: ${SKILL_DESCRIPTION}`]
+
+  if (target.frontmatterProfile === 'claude') {
+    lines.push('argument-hint: [request]')
+  }
+
+  if (target.frontmatterProfile === 'copilot') {
+    lines.push('license: MIT')
+  }
+
+  lines.push('---', '')
+  return `${lines.join('\n')}\n`
+}
+
+function renderOpenAIMetadata(): string {
+  return `interface:
+  display_name: "Agent Context"
+  short_description: "统一管理 .agent-context 计划生命周期"
+  default_prompt: "Use $ac-workflow to manage the current task through init, plan, replan, implement, patch, rush, or done."
+
+policy:
+  allow_implicit_invocation: true
+`
+}

package/src/context/archiver.ts

@@ -0,0 +1,45 @@
+import { rename, mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import type { ArchiveResult, ContextSnapshot } from '../types.js'
+
+export async function archive(context: ContextSnapshot): Promise<ArchiveResult> {
+  if (!context.currentPlan) {
+    throw new Error('无当前计划')
+  }
+
+  if (context.currentPlan.status !== '已执行') {
+    throw new Error('当前计划尚未执行')
+  }
+
+  const archiveName = `plan-${context.currentPlan.number}-${formatDate()}`
+  const doneDir = join(context.root, 'done')
+  const archivedTo = join(doneDir, archiveName)
+
+  await mkdir(doneDir, { recursive: true })
+  await rename(context.currentPlan.dir, archivedTo)
+
+  let promoted: number | null = null
+  const first = context.preparing[0]
+  if (first) {
+    const targetDir = join(context.root, `plan-${first.number}`)
+    await rename(first.dir, targetDir)
+    promoted = first.number
+  }
+
+  return {
+    archivedTo,
+    promoted,
+    remainingPreparing: context.preparing.length - (promoted !== null ? 1 : 0)
+  }
+}
+
+// ── Helpers ──────────────────────────────────────────
+
+function formatDate(): string {
+  const d = new Date()
+  const y = String(d.getFullYear())
+  const m = String(d.getMonth() + 1).padStart(2, '0')
+  const day = String(d.getDate()).padStart(2, '0')
+  return `${y}${m}${day}`
+}

package/src/context/index.ts

@@ -0,0 +1,3 @@
+export { readContext, readRawContext, readPlanStatus } from './reader.js'
+export { validate } from './validator.js'
+export { archive } from './archiver.js'

package/src/context/reader.ts

@@ -0,0 +1,77 @@
+import { readdir, readFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { ContextSnapshot, PlanInfo, PlanStatus } from '../types.js'
+
+const PLAN_DIR_RE = /^plan-(\d+)$/
+const STATUS_RE = /^>\s*状态:\s*(未执行|已执行)\s*$/m
+
+// ── Public API ───────────────────────────────────────
+
+export async function readContext(cwd: string): Promise<ContextSnapshot | null> {
+  const { snapshot } = await readRawContext(cwd)
+  return snapshot
+}
+
+export async function readRawContext(
+  cwd: string
+): Promise<{ snapshot: ContextSnapshot | null; currentPlanCount: number }> {
+  const root = join(cwd, '.agent-context')
+
+  if (!existsSync(root)) {
+    return { snapshot: null, currentPlanCount: 0 }
+  }
+
+  const currentPlans = await readPlanDirs(root)
+  const preparing = await readPlanDirs(join(root, 'preparing'))
+  const doneCount = await countDirs(join(root, 'done'))
+
+  const snapshot: ContextSnapshot = {
+    root,
+    currentPlan: currentPlans[0] ?? null,
+    preparing,
+    doneCount
+  }
+
+  return { snapshot, currentPlanCount: currentPlans.length }
+}
+
+export async function readPlanStatus(planDir: string): Promise<PlanStatus> {
+  const planFile = join(planDir, 'plan.md')
+
+  if (!existsSync(planFile)) {
+    return '未执行'
+  }
+
+  const content = await readFile(planFile, 'utf-8')
+  const match = content.match(STATUS_RE)
+  return match ? (match[1] as PlanStatus) : '未执行'
+}
+
+// ── Helpers ──────────────────────────────────────────
+
+async function readPlanDirs(parentDir: string): Promise<PlanInfo[]> {
+  if (!existsSync(parentDir)) return []
+
+  const entries = await readdir(parentDir, { withFileTypes: true })
+  const plans: PlanInfo[] = []
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue
+    const match = entry.name.match(PLAN_DIR_RE)
+    if (!match?.[1]) continue
+    const number = parseInt(match[1], 10)
+    const dir = join(parentDir, entry.name)
+    const status = await readPlanStatus(dir)
+    plans.push({ number, status, dir })
+  }
+
+  return plans.sort((a, b) => a.number - b.number)
+}
+
+async function countDirs(dir: string): Promise<number> {
+  if (!existsSync(dir)) return 0
+  const entries = await readdir(dir, { withFileTypes: true })
+  return entries.filter(e => e.isDirectory()).length
+}

package/src/context/validator.ts

@@ -0,0 +1,44 @@
+import { existsSync } from 'node:fs'
+import { join } from 'node:path'
+
+import type { ContextSnapshot, ValidateResult } from '../types.js'
+
+export function validate(
+  snapshot: ContextSnapshot | null,
+  currentPlanCount: number
+): ValidateResult {
+  if (snapshot === null) {
+    return { valid: true, errors: [], context: null }
+  }
+
+  const errors: string[] = []
+
+  if (currentPlanCount > 1) {
+    errors.push(`存在 ${currentPlanCount} 个当前计划，应最多 1 个。`)
+  }
+
+  if (snapshot.currentPlan) {
+    const planMd = join(snapshot.currentPlan.dir, 'plan.md')
+    if (!existsSync(planMd)) {
+      errors.push(`当前计划 plan-${snapshot.currentPlan.number} 缺少 plan.md。`)
+    }
+  }
+
+  const allNumbers: number[] = []
+  if (snapshot.currentPlan) allNumbers.push(snapshot.currentPlan.number)
+  for (const p of snapshot.preparing) allNumbers.push(p.number)
+
+  const seen = new Set<number>()
+  const duplicates = new Set<number>()
+  for (const n of allNumbers) {
+    if (seen.has(n)) duplicates.add(n)
+    seen.add(n)
+  }
+
+  if (duplicates.size > 0) {
+    const nums = [...duplicates].sort((a, b) => a - b).join(', ')
+    errors.push(`计划编号冲突: ${nums}。`)
+  }
+
+  return { valid: errors.length === 0, errors, context: snapshot }
+}

package/src/runner.ts

@@ -0,0 +1,113 @@
+import { resolve, dirname } from 'node:path'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+
+import type { SkillPaths } from './tools.js'
+import { resolveToolTargets, resolveSkillPaths } from './tools.js'
+import { renderSkillArtifacts } from './content/index.js'
+import type { ApplyMutationResult, FileMutation, RunOptions, RunResult, ToolId, ToolTarget } from './types.js'
+
+export async function runInstall(options: RunOptions = {}): Promise<RunResult> {
+  return run('install', options)
+}
+
+export async function runSync(options: RunOptions = {}): Promise<RunResult> {
+  return run('sync', options)
+}
+
+// ── Orchestration ───────────────────────────────────
+
+async function run(mode: 'install' | 'sync', options: RunOptions): Promise<RunResult> {
+  const cwd = options.cwd ?? process.cwd()
+  const tools = dedup(options.tools)
+  const targets = resolveToolTargets(tools)
+
+  const mutations: FileMutation[] = targets.flatMap(target => buildMutations(target, cwd))
+
+  const check = options.check ?? false
+  const result = await applyMutations(mutations, check)
+
+  return { ...result, mode, check }
+}
+
+// ── Mutation building ───────────────────────────────
+
+function buildMutations(target: ToolTarget, cwd: string): FileMutation[] {
+  const artifacts = renderSkillArtifacts(target)
+  const paths = resolveSkillPaths(target, cwd)
+
+  return artifacts.files.map(file => ({
+    path: resolveArtifactPath(paths, file.relativePath),
+    body: file.body
+  }))
+}
+
+function resolveArtifactPath(paths: SkillPaths, relativePath: string): string {
+  if (relativePath === 'SKILL.md') {
+    return paths.skillFile
+  }
+
+  return resolve(paths.skillDir, relativePath)
+}
+
+// ── Mutation application ────────────────────────────
+
+async function applyMutations(
+  mutations: FileMutation[],
+  check: boolean
+): Promise<ApplyMutationResult> {
+  const result: ApplyMutationResult = {
+    created: [],
+    updated: [],
+    unchanged: [],
+    changed: []
+  }
+
+  for (const mutation of mutations) {
+    const fileExists = existsSync(mutation.path)
+    const next = await resolveNextContent(mutation, fileExists)
+
+    if (!next.changed) {
+      result.unchanged.push(mutation.path)
+      continue
+    }
+
+    if (!check) {
+      await mkdir(dirname(mutation.path), { recursive: true })
+      await writeFile(mutation.path, next.content, 'utf-8')
+    }
+
+    result.changed.push(mutation.path)
+
+    if (fileExists) {
+      result.updated.push(mutation.path)
+    } else {
+      result.created.push(mutation.path)
+    }
+  }
+
+  return result
+}
+
+async function resolveNextContent(
+  mutation: FileMutation,
+  fileExists: boolean
+): Promise<{ content: string; changed: boolean }> {
+  const content = normalizeTrailingNewline(mutation.body)
+
+  if (!fileExists) {
+    return { content, changed: true }
+  }
+
+  const current = await readFile(mutation.path, 'utf-8')
+  return { content, changed: current !== content }
+}
+
+function normalizeTrailingNewline(content: string): string {
+  return content.endsWith('\n') ? content : `${content}\n`
+}
+
+function dedup(tools?: ToolId[]): ToolId[] | undefined {
+  if (!tools || tools.length === 0) return undefined
+  return [...new Set(tools)]
+}