@cat-kit/agent-context 1.0.3

package/src/domain/workflow-templates/plan.ts

@@ -0,0 +1,70 @@
+import {
+  code,
+  fence,
+  renderNextSteps,
+  renderPreamble,
+  type WorkflowContext
+} from '../workflow-context'
+
+export function renderPlan(c: WorkflowContext): string {
+  return `${c.frontmatter('创建新计划并维护单当前计划 + preparing 队列结构')}\
+# ${c.invoke('plan')} {描述}
+
+${renderPreamble(c, 'plan', `创建新的执行计划，写入 ${code('.agent-context/plan-{number}/plan.md')}。按复杂度可拆分为多个计划，维护「单当前计划 + preparing 队列」结构。`)}
+
+## 前置规则
+
+- 描述为空 → 拒绝执行，提示必须附带描述。
+- 存在未归档的已执行当前计划 → 拒绝执行，提示先运行 ${code(c.cmd('done'))}。
+- 存在多个当前计划 → 拒绝执行，提示恢复单活跃状态。
+- 编号：扫描 ${code('.agent-context/{,preparing/,done/}')} 全部 ${code('plan-N')}，取 max(N)+1，不复用。
+
+## 执行步骤
+
+1. **需求澄清**（存在以下任一歧义时必须向用户提问，否则直接跳到步骤 2）：
+   - 范围边界不清：无法判定影响哪些文件或模块。
+   - 存在显著不同的技术路径需用户决策。
+   - 验收标准不明确：无法判断何时算"完成"。
+2. 按复杂度决定单计划或多计划拆分。
+3. 多计划拆分时：最小编号进入 ${code('.agent-context/')} 作为当前计划，其余进入 ${code('.agent-context/preparing/')}。单计划直接创建到 ${code('.agent-context/plan-{number}')}。
+4. 每个计划创建 ${code('plan.md')}，遵循下方标准模板。
+5. **计划自检**（不通过则修改后重新检查）：
+   - 每个步骤可独立执行且有明确完成标准。
+   - 不存在过度拆分（过于琐碎）或拆分不足（单步骤过于复杂）。
+   - 影响范围可预估。
+
+## plan.md 标准模板
+
+${fence}markdown
+# {计划名称}
+
+> 状态: 未执行
+
+## 目标
+
+{明确的目标描述}
+
+## 内容
+
+{详细的实施步骤和内容}
+
+## 影响范围
+
+- 新增文件: \`/path/to/file\`
+- 修改文件: \`/path/to/file\`
+- 删除文件: \`/path/to/file\`
+
+## 历史补丁
+
+- patch-1: {补丁名称}
+${fence}
+
+- 状态行唯一，仅允许 ${code('未执行')} 或 ${code('已执行')}。
+- ${code('## 目标')} 与 ${code('## 内容')} 不可为空。
+- ${code('## 影响范围')} 与 ${code('## 历史补丁')} 创建时留空，分别由 ${code(c.cmd('implement'))} 和 ${code(c.cmd('patch'))} 写入。
+
+${renderNextSteps(c, [
+  { command: 'implement', description: '实施当前计划' },
+  { command: 'replan', description: '调整计划' }
+])}`
+}

package/src/domain/workflow-templates/replan.ts

@@ -0,0 +1,36 @@
+import { code, renderNextSteps, renderPreamble, type WorkflowContext } from '../workflow-context'
+
+export function renderReplan(c: WorkflowContext): string {
+  return `${c.frontmatter('重规划未实施计划，保持单当前计划结构不变')}\
+# ${c.invoke('replan')} {描述}
+
+${renderPreamble(c, 'replan', `重新规划已有的未实施计划（${code('preparing/')} 队列或未执行的当前计划），保持单当前计划结构不变。`)}
+
+## 前置规则
+
+- 描述为空 → 拒绝执行。
+- 无未实施计划 → 拒绝执行，提示使用 ${code(c.cmd('plan'))} 创建。
+- 存在多个当前计划 → 拒绝执行，提示恢复单活跃状态。
+- 目标计划编号不存在 → 拒绝执行，列出可选编号。
+- 目标计划已执行 → 拒绝执行，提示使用 ${code(c.cmd('patch'))} 修补。
+- 重规划后违反单当前计划约束 → 回滚并报错。
+
+## 作用域规则
+
+- 默认作用域：${code('.agent-context/preparing/')} 中全部未实施计划。
+- 可通过描述指定仅重规划部分计划（如"重规划 plan-3 和 plan-5"）。
+- 当前计划为 ${code('已执行')} → 禁止重写，仅允许重规划 ${code('preparing/')} 队列。
+- 当前计划为 ${code('未执行')} 且用户明确要求 → 可纳入重规划范围。
+
+## 执行步骤
+
+1. 解析描述，确定重规划目标范围。
+2. 读取目标计划 ${code('plan.md')}，理解现有意图。
+3. 生成新的拆分方案，保持"单当前计划 + 若干 preparing 计划"结构。
+4. 新增计划编号：全局 max(N)+1 递增分配；未改动计划保持原编号。
+5. 更新目录结构，确保每个新计划的 ${code('plan.md')} 遵循标准模板。
+
+${renderNextSteps(c, [
+  { command: 'implement', description: '实施当前计划' }
+])}`
+}

package/src/generators/workflow.ts

@@ -0,0 +1,25 @@
+import { resolveWorkflowPaths } from '../adapters/tool-targets'
+import type { FileMutation, ToolTarget, WorkflowCommandName } from '../domain/types'
+import { renderWorkflowArtifacts } from '../domain/workflow-content'
+
+const COMMAND_ORDER: WorkflowCommandName[] = [
+  'init',
+  'plan',
+  'replan',
+  'implement',
+  'patch',
+  'done'
+]
+
+export function renderWorkflowMutations(target: ToolTarget, cwd: string): FileMutation[] {
+  const artifacts = renderWorkflowArtifacts(target)
+  const paths = resolveWorkflowPaths(target, cwd)
+
+  const mutations: FileMutation[] = []
+
+  for (const command of COMMAND_ORDER) {
+    mutations.push({ path: paths.commandFile(command), body: artifacts.commandFiles[command] })
+  }
+
+  return mutations
+}

package/src/index.ts

@@ -0,0 +1,11 @@
+export { resolveToolTargets, parseToolIds, resolveWorkflowPaths } from './adapters/tool-targets'
+export { renderWorkflowArtifacts } from './domain/workflow-content'
+export { runSetup, runUpdate } from './runtime/execute'
+export type {
+  ToolId,
+  ToolTarget,
+  RunOptions,
+  RunResult,
+  WorkflowArtifacts,
+  WorkflowCommandName
+} from './domain/types.js'

package/src/runtime/execute.ts

@@ -0,0 +1,45 @@
+import { resolveToolTargets } from '../adapters/tool-targets'
+import type { FileMutation, RunOptions, RunResult, ToolId } from '../domain/types'
+import { renderWorkflowMutations } from '../generators/workflow'
+import { applyManagedMutations } from '../shared/fs'
+
+export async function runSetup(options: RunOptions = {}): Promise<RunResult> {
+  return runInMode('setup', options)
+}
+
+export async function runUpdate(options: RunOptions = {}): Promise<RunResult> {
+  return runInMode('update', options)
+}
+
+async function runInMode(mode: 'setup' | 'update', options: RunOptions): Promise<RunResult> {
+  const cwd = options.cwd ?? process.cwd()
+  const toolIds = normalizeTools(options.tools)
+  const targets = resolveToolTargets(toolIds)
+
+  const mutations: FileMutation[] = targets.flatMap(target => renderWorkflowMutations(target, cwd))
+
+  const check = options.check ?? false
+  const result = await applyManagedMutations(mutations, check)
+
+  return {
+    ...result,
+    mode,
+    check
+  }
+}
+
+function normalizeTools(tools?: ToolId[]): ToolId[] | undefined {
+  if (!tools || tools.length === 0) {
+    return undefined
+  }
+
+  const uniqueTools: ToolId[] = []
+
+  for (const tool of tools) {
+    if (!uniqueTools.includes(tool)) {
+      uniqueTools.push(tool)
+    }
+  }
+
+  return uniqueTools
+}

package/src/shared/fs.ts

@@ -0,0 +1,66 @@
+import { dirname } from 'node:path'
+import { existsSync } from 'node:fs'
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+
+import type { ApplyMutationResult, FileMutation } from '../domain/types'
+
+export async function applyManagedMutations(
+  mutations: FileMutation[],
+  check: boolean
+): Promise<ApplyMutationResult> {
+  const result: ApplyMutationResult = {
+    created: [],
+    updated: [],
+    unchanged: [],
+    changed: []
+  }
+
+  for (const mutation of mutations) {
+    const fileExists = existsSync(mutation.path)
+    const nextContent = await resolveNextContent(mutation, fileExists)
+
+    if (!nextContent.changed) {
+      result.unchanged.push(mutation.path)
+      continue
+    }
+
+    if (!check) {
+      await mkdir(dirname(mutation.path), { recursive: true })
+      await writeFile(mutation.path, nextContent.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 nextContent = normalizeTrailingNewline(mutation.body)
+
+  if (!fileExists) {
+    return {
+      content: nextContent,
+      changed: true
+    }
+  }
+
+  const currentContent = await readFile(mutation.path, 'utf-8')
+  return {
+    content: nextContent,
+    changed: currentContent !== nextContent
+  }
+}
+
+function normalizeTrailingNewline(content: string): string {
+  return content.endsWith('\n') ? content : `${content}\n`
+}

package/src/shared/paths.ts

@@ -0,0 +1,9 @@
+import { dirname, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const __filename = fileURLToPath(import.meta.url)
+const __dirname = dirname(__filename)
+
+export function getPackageRootDir(): string {
+  return resolve(__dirname, '../..')
+}