从 Claude Code 反推 AI 编码 Agent 的工程架构

type UserTask = {
  goal: string;
  repoPath: string;
};

type ContextItem = {
  kind: "rule" | "file" | "search" | "diff" | "command";
  title: string;
  content: string;
  priority: number;
};

type ContextBudget = {
  maxTokens: number;
};

async function buildContext(task: UserTask, budget: ContextBudget): Promise<string> {
  const items: ContextItem[] = [];

  const rules = await readProjectRules(task.repoPath);
  items.push({
    kind: "rule",
    title: "Project Rules",
    content: rules,
    priority: 100,
  });

  const keywords = extractSearchKeywords(task.goal);
  const matches = await searchRepository(task.repoPath, keywords);

  items.push({
    kind: "search",
    title: "Search Results",
    content: formatSearchResults(matches),
    priority: 80,
  });

  const candidateFiles = rankFilesByRelevance(matches, task.goal);
  for (const file of candidateFiles.slice(0, 8)) {
    const snippet = await readRelevantSnippet(file, task.goal);
    items.push({
      kind: "file",
      title: file.path,
      content: snippet,
      priority: file.score,
    });
  }

  const currentDiff = await gitDiff(task.repoPath);
  if (currentDiff.trim()) {
    items.push({
      kind: "diff",
      title: "Current Diff",
      content: currentDiff,
      priority: 90,
    });
  }

  return packByPriority(items, budget.maxTokens);
}

{
  "name": "read_file",
  "description": "读取工作区内的文本文件",
  "input_schema": {
    "type": "object",
    "properties": {
      "path": {
        "type": "string",
        "description": "相对于工作区根目录的文件路径"
      },
      "start_line": {
        "type": "number",
        "description": "起始行号，从 1 开始"
      },
      "end_line": {
        "type": "number",
        "description": "结束行号"
      }
    },
    "required": ["path"]
  },
  "permission": "read_workspace"
}

{
  "name": "run_command",
  "description": "在工作区内执行命令，默认不允许访问网络和工作区外路径",
  "input_schema": {
    "type": "object",
    "properties": {
      "command": {
        "type": "string"
      },
      "timeout_ms": {
        "type": "number"
      },
      "reason": {
        "type": "string",
        "description": "说明为什么需要执行该命令"
      }
    },
    "required": ["command", "reason"]
  },
  "permission": "execute_command"
}

import path from "node:path";

function assertInsideWorkspace(workspaceRoot: string, inputPath: string) {
  const resolved = path.resolve(workspaceRoot, inputPath);
  const root = path.resolve(workspaceRoot);

  if (!resolved.startsWith(root + path.sep) && resolved !== root) {
    throw new Error(`Path escapes workspace: ${inputPath}`);
  }

  return resolved;
}

const blockedPatterns = [
  /\.env(\..*)?$/,
  /id_rsa$/,
  /id_ed25519$/,
  /credentials\.json$/,
  /kubeconfig$/,
  /\.npmrc$/,
];

function isSensitivePath(filePath: string) {
  return blockedPatterns.some((pattern) => pattern.test(filePath));
}

function redactSecrets(output: string) {
  return output
    .replace(/AKIA[0-9A-Z]{16}/g, "[REDACTED_AWS_KEY]")
    .replace(/ghp_[A-Za-z0-9_]{30,}/g, "[REDACTED_GITHUB_TOKEN]")
    .replace(/-----BEGIN [A-Z ]+PRIVATE KEY-----[\s\S]+?-----END [A-Z ]+PRIVATE KEY-----/g, "[REDACTED_PRIVATE_KEY]");
}

diff --git a/src/auth/session.ts b/src/auth/session.ts
index 7a1c9a2..3b2f8c1 100644
--- a/src/auth/session.ts
+++ b/src/auth/session.ts
@@ -18,7 +18,11 @@ export async function getSession(userId: string) {
   const cached = await cache.get(cacheKey);
   if (cached) return JSON.parse(cached);
 
-  const session = await db.session.findFirst({ where: { userId } });
+  const session = await db.session.findFirst({
+    where: { userId, revokedAt: null },
+    orderBy: { createdAt: "desc" },
+  });
+
   if (!session) return null;
 
   await cache.set(cacheKey, JSON.stringify(session), 300);

# Agent Instructions

## Project
- Runtime: Node.js 20
- Package manager: pnpm
- Main framework: Fastify
- ORM: Prisma

## Commands
- Install: pnpm install
- Type check: pnpm typecheck
- Test: pnpm test
- Lint: pnpm lint

## Coding Rules
- Do not access Prisma client directly in controllers.
- Put business logic in `src/modules/*/service.ts`.
- Use `AppError` for business errors.
- Add or update tests for behavior changes.

## Safety
- Do not read `.env*` files.
- Do not run database migration commands unless explicitly requested.

{
  "task_id": "fix-login-500",
  "goal": "修复登录接口 500 错误",
  "plan": [
    {
      "step": "定位登录接口实现",
      "status": "done"
    },
    {
      "step": "修复 session 查询逻辑",
      "status": "done"
    },
    {
      "step": "运行认证模块测试",
      "status": "running"
    }
  ],
  "touched_files": [
    "src/auth/session.ts",
    "src/auth/session.test.ts"
  ],
  "last_observation": "1 个测试失败：should reject revoked session"
}

pnpm typecheck
pnpm test src/auth/session.test.ts
pnpm lint

{
  "timestamp": "2026-06-07T10:30:00+08:00",
  "tool": "run_command",
  "input": {
    "command": "pnpm test src/auth/session.test.ts",
    "reason": "验证 session 查询逻辑修改"
  },
  "permission": "safe_command",
  "status": "success",
  "duration_ms": 3821,
  "output_preview": "12 passed"
}

git status --short

git diff -- src/auth/session.ts src/auth/session.test.ts

[
  {
    "name": "fix-null-session",
    "goal": "修复 session 为空时登录接口返回 500 的问题",
    "expected_files": [
      "src/auth/session.ts",
      "src/auth/session.test.ts"
    ],
    "validation": [
      "pnpm test src/auth/session.test.ts",
      "pnpm typecheck"
    ]
  },
  {
    "name": "add-order-cancel-api",
    "goal": "为订单模块增加取消接口，只有待支付订单可以取消",
    "expected_files": [
      "src/modules/order/controller.ts",
      "src/modules/order/service.ts",
      "src/modules/order/service.test.ts"
    ],
    "validation": [
      "pnpm test src/modules/order",
      "pnpm lint"
    ]
  }
]