agent-guardrails 0.3.0 → 0.3.3

package/README.md

@@ -1,13 +1,165 @@
 # Agent Guardrails
 
-**3 seconds to know: Can you safely merge this AI change?**
+**3 秒判断：这次 AI 改动可以安全 merge 吗？**
 
-`agent-guardrails` is the merge gate for AI-written code. It tells you:
-- ✅ **Safe to merge** — scope is bounded, tests pass, no drift
-- ⚠️ **Needs review** — some risk signals, check these files
-- ❌ **Don't merge** — out of scope, missing tests, or breaking changes
+[中文简介](#中文简介) | [Quick Start](#快速开始--先看这里) | [Docs](#文档--documentation)
+
+`agent-guardrails` 是 **AI 代码合并门** - 在 merge 前检查 AI 改动是否符合预期。
+
+- 🎯 **范围验证** - AI 只改了允许的文件
+- ✅ **测试验证** - 测试必须运行
+- 🔍 **漂移检测** - 检测并行抽象、接口变更
+- 🛡 **保护路径** - 关键文件不被触碰
+
+## How it works
+
+![Workflow](./docs/images/workflow.svg)
+
+---
+
+## Before vs After
+
+![Before vs After](./docs/images/before-after.svg)
+
+---
+
+## Rough-Intent Mode
+
+Don't have a precise task? Just say what you want in natural language:
+
+![Rough-Intent Mode](./docs/images/rough-intent.svg)
+
+```bash
+# No detailed flags needed - just describe your task
+agent-guardrails plan "加个登录功能" --lang zh-CN --yes
+```
+
+---
+
+## 快速开始 / 先看这里
+
+**30 秒快速体验**（推荐）
+
+```bash
+# 1. 安装
+npm install -g agent-guardrails
+
+# 2. 在项目中设置
+cd your-repo
+agent-guardrails setup --agent claude-code
+```
+
+你可以用其他 Agent：
+- `claude-code` - Claude Code CLI
+- `cursor` - Cursor Editor
+- `codex` - OpenAI Codex CLI
+- `openhands` - OpenHands CLI
+- `openclaw` - OpenClaw CLI
+
+**注意**： `setup` 会在项目根目录生成配置文件，输出使用指南。
+
+请复制输出的配置片段到 粘贴到你的 AI 工具中。
+
+**3. 开始使用**
+让你的 AI 按照指南操作代码
+- 输入 `/init` 开始新任务
+- 输入 `/plan` 创建任务计划
+- 输入 `/check` 在完成后检查
+
+- 使用 `/review` 获取合并建议
+
+**4. 在 merge 前运行检查**
+```bash
+agent-guardrails check --review
+```
+
+---
+
+## 核心价值 / Core Value
+
+### 与 传统 AI 编码 | 使用 agent-guardrails |
+|---------------|---------------------------|
+| "AI 改了 47 个文件，不知道为什么" | "AI 改了 3 个文件,都在范围内" |
+| "应该测试过了？" | "测试运行完成，12 通过，0 失败" |
+| "这看起来像是个新模式" | "⚠️ 检测到并行抽象" |
+| "希望不会出问题" | "✓ 可以安全 merge，剩余风险：低" |
+| 5 files, clear scope, clear validation | 12 passed, 0 failed | 0 files, clear scope, clear validation | safe to merge, remaining risk: low |
+
+---
+
+## 适用场景 / When to Use
+
+| 场景 | 推荐度 |
+|------|--------|
+| 在真实仓库中使用 AI Agent 的开发者 | ⭐⭐⭐⭐⭐ |
+| 被越界改动、漏测试坑过的团队 | ⭐⭐⭐⭐⭐ |
+| 希望在 merge 前看到清晰验证结果的人 | ⭐⭐⭐⭐ |
+
+**不适用场景**：
+- 只想做一次性 prototype 的用户
+- 不关心代码质量和维护性的团队
+- 想找通用静态分析工具的用户
+
+---
+
+## 与竞品对比 / vs. Competitors
+
+| 功能 | CodeRabbit | Sonar | agent-guardrails |
+|------|-----------|-------|------------------|
+| 事前约束 | ❌ 事后评论 | ❌ 事后检查 | ✅ |
+| 范围控制 | ❌ | ❌ | ✅ |
+| 任务上下文 | ❌ | ❌ | ✅ |
+| 测试相关性检查 | ❌ | ❌ | ✅ |
+
+**我们的优势**： 在代码生成**之前**定义边界，而不是生成**之后**发现问题
+- 主动而非被动
+- 与 AI Agent 巷度集成
+- 支持多种编程语言
+
+- 完全开源免费
+
+---
+
+## 安装 / Installation
+
+```bash
+npm install -g agent-guardrails
+```
+
+在项目目录运行：
+```bash
+npx agent-guardrails setup --agent <your-agent>
+```
+
+支持的 Agent：
+- `claude-code` (推荐)
+- `cursor`
+- `codex`
+- `openhands`
+- `openclaw`
+
+---
+
+## 文档 / Documentation
+
+- [README.md](./README.md) - 你文档
+- [FAILURE Cases](./docs/FAILURE_Cases.md) - 真实失败案例
+- [Rough-Intent Mode](./docs/Rrough_intent.md) - 模糊请求处理
+- [OSS/Pro 边界](./docs/oss_pro_boundary.md) - 功能对比
+
+- [Roadmap](./docs/roadmap.md) - 发展规划
+
+- [Proof](./docs/proof.md) - 效果证明
+
+- [Pilots](./docs/pilots/README.md) - 试点记录
+
+- [Python FastAPI Demo](./examples/python-fastapi-demo/README.md) - Python 示例
+- [TypeScript Demo](./examples/pattern-drift-demo/README.md) - TypeScript 示例
+- [Bounded Scope Demo](./examples/bounded-scope-demo/README.md) - 范围控制示例
+- [Boundary Demo](./examples/boundary-violation-demo/README.md) - 边界检查示例
+- [Interface Drift Demo](./examples/interface-drift-demo/README.md) - 接口变更示例
+- [Source-Test Relevance Demo](./examples/source-test-relevance-demo/README.md) - 测试相关性示例
 
-For real repos, not one-off prototypes.
 
 ---
 
@@ -371,6 +523,58 @@ The first recommended MCP flow is:
 
 `suggest_task_contract` and `run_guardrail_check` still exist as lower-level MCP tools, but they are not the preferred first-run chat flow.
 
+## Daemon Mode / 守护进程模式
+
+Run guardrails automatically in the background while you code:
+
+```bash
+# Start the daemon (background mode)
+agent-guardrails start
+
+# Check daemon status
+agent-guardrails status
+
+# Stop the daemon
+agent-guardrails stop
+
+# Run in foreground (useful for debugging or Docker)
+agent-guardrails start --foreground
+```
+
+### How It Works
+
+The daemon monitors file changes and automatically runs guardrail checks:
+- Watches `src/`, `lib/`, `tests/` by default
+- Debounces checks (5 second interval)
+- Logs to `.agent-guardrails/daemon.log`
+
+### Configuration (`.agent-guardrails/daemon.json`)
+
+| Option | Default | Description |
+|--------|---------|-------------|
+| `watchPaths` | `["src/", "lib/", "tests/"]` | Paths to monitor |
+| `ignorePatterns` | `["node_modules", ".git", ...]` | Patterns to ignore |
+| `checkInterval` | `5000` | Debounce interval (ms) |
+| `blockOnHighRisk` | `true` | Block on high-risk findings |
+| `autoFix` | `false` | Auto-fix issues when possible |
+
+### Use Cases
+
+- **Local development**: Get instant feedback while coding
+- **CI/CD integration**: Run in containers with `--foreground`
+- **Team guardrails**: Shared daemon config in repo
+
+### Daemon vs Manual Check
+
+| Daemon Mode | Manual Check |
+|-------------|--------------|
+| Continuous monitoring | One-time check |
+| Automatic on file change | Run when you want |
+| Background process | Foreground process |
+| Best for active development | Best for pre-commit/CI |
+
+---
+
 ## CLI Fallback Quick Start
 
 If you want the shortest manual path, copy this:
@@ -639,3 +843,13 @@ See [CHANGELOG.md](./CHANGELOG.md).
 ## License
 
 MIT
+
+---
+
+## Contributing / 贡献
+
+- 🐛 **Bug Reports**: [Open an Issue](https://github.com/logi-cmd/agent-guardrails/issues/new)
+- 💡 **Feature Requests**: [Start a Discussion](https://github.com/logi-cmd/agent-guardrails/discussions)
+- ❓ **Questions**: [Ask in Discussions](https://github.com/logi-cmd/agent-guardrails/discussions)
+
+If you find this project helpful, please consider giving it a ⭐️!

package/lib/check/detectors/oss.js

@@ -1,5 +1,6 @@
 import { createFinding } from "../finding.js";
 import { normalizeChangeType } from "../../utils.js";
+import { execFileSync } from "node:child_process";
 
 function toBoolean(value) {
   if (value === true || value === false) {
@@ -461,5 +462,63 @@ export const ossDetectors = [
         }));
       }
     }
+  },
+  {
+    name: "secrets-safety",
+    run({ context, addFinding, t }) {
+      const { repoRoot, changedFiles } = context;
+      if (!changedFiles || changedFiles.length === 0) return;
+
+      const patterns = [
+        { regex: /(?:api[_-]?key|apikey)\s*[=:]\s*["'][^"']{8,}["']/i, label: "API key" },
+        { regex: /(?:password|passwd|pwd)\s*[=:]\s*["'][^"']{6,}["']/i, label: "Password" },
+        { regex: /Bearer\s+[A-Za-z0-9\-._~+/]+=*/i, label: "Bearer token" },
+        { regex: /-----BEGIN(?:\s+(?:RSA|EC|DSA|OPENSSH|PRIVATE))?[\s-]*PRIVATE KEY-----/, label: "Private key" },
+        { regex: /(?:secret|token)\s*[=:]\s*["'][A-Za-z0-9\-._~+/]{16,}["']/i, label: "Secret/token" }
+      ];
+
+      const testLike = /\.(test|spec)\.(js|ts|mjs|cjs|jsx|tsx)$|__tests__|fixtures|mock/i;
+      let matched = false;
+
+      for (const filePath of changedFiles) {
+        if (testLike.test(filePath)) continue;
+        let content;
+        try {
+          content = execFileSync(
+            "git",
+            ["diff", "--cached", "--", filePath],
+            { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
+          );
+          if (!content.trim()) {
+            content = execFileSync(
+              "git",
+              ["diff", "--", filePath],
+              { cwd: repoRoot, encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] }
+            );
+          }
+        } catch {
+          continue;
+        }
+        const addedLines = content.split("\n").filter((line) => /^\+/.test(line) && !/^\+\+\+/.test(line));
+        for (const { regex, label } of patterns) {
+          for (const line of addedLines) {
+            if (regex.test(line)) {
+              matched = true;
+              addFinding(createFinding({
+                severity: "warning",
+                category: "risk",
+                code: "secrets-safety",
+                message: t("findings.secretsSafetyDetected", { file: filePath, type: label }),
+                action: t("actions.moveSecretToEnv"),
+                files: [filePath]
+              }));
+              break;
+            }
+          }
+          if (matched) break;
+        }
+        if (matched) break;
+      }
+    }
   }
 ];

package/lib/cli.js

@@ -4,7 +4,9 @@ import { runMcp } from "./commands/mcp.js";
 import { runSetup } from "./commands/setup.js";
 import { createTranslator, supportedLocales } from "./i18n.js";
 import { runPlan } from "./commands/plan.js";
-import { supportedAdapters, supportedPresets } from "./utils.js";
+import { runGenerateAgentsMd } from "./commands/agents-md.js";
+import { startDaemon, stopDaemon, showDaemonStatus } from "./commands/daemon.js";
+import { supportedAdapters, supportedPresets, readOwnPackageJson } from "./utils.js";
 
 function parseArgs(argv) {
   const positional = [];
@@ -42,14 +44,28 @@ ${t("cli.usage")}
   agent-guardrails setup [targetDir] --agent <name> [--preset <name>] [--lang <locale>] [--json] [--write-repo-config]
   agent-guardrails plan --task "<task description>" [--intended-files "src/service.js,tests/service.test.js"] [--allowed-change-types "implementation-only"] [--allow-paths "src/,tests/"] [--required-commands "npm test"] [--evidence ".agent-guardrails/evidence/current-task.md"] [--risk-level high] [--lang <locale>] [--print-only]
   agent-guardrails check [--contract-path <path>] [--base-ref <ref>] [--commands-run "npm test"] [--review] [--lang <locale>] [--json]
+  agent-guardrails start [--foreground] - ${t("cli.startSummary")}
+  agent-guardrails stop    - ${t("cli.stopSummary")}
+  agent-guardrails status  - ${t("cli.statusSummary")}
+  agent-guardrails generate-agents [targetDir] [--preset <name>] [--lang <locale>]
   agent-guardrails mcp
+  agent-guardrails --version
+
+${t("cli.globalOptions")}
+  --version, -v    ${t("cli.versionSummary") ?? "Show version number"}
+  --help, -h       ${t("cli.helpSummary") ?? "Show this help"}
+  --lang <locale>  ${t("cli.langSummary") ?? "Language for output (en, zh-CN)"}
 
 ${t("cli.commands")}
-  init   ${t("cli.initSummary")}
-  setup  ${t("cli.setupSummary")}
-  plan   ${t("cli.planSummary")}
-  check  ${t("cli.checkSummary")}
-  mcp    ${t("cli.mcpSummary")}
+  init            ${t("cli.initSummary")}
+  setup           ${t("cli.setupSummary")}
+  plan            ${t("cli.planSummary")}
+  check           ${t("cli.checkSummary")}
+  start           ${t("cli.startSummary")}
+  stop            ${t("cli.stopSummary")}
+  status          ${t("cli.statusSummary")}
+  generate-agents Generate AGENTS.md for Harness Engineering
+  mcp             ${t("cli.mcpSummary")}
 
 ${t("cli.supportedPresets")}
   ${supportedPresets.join(", ")}
@@ -67,6 +83,12 @@ export async function runCli(argv) {
   const [command, ...rest] = positional;
   const locale = flags.lang ?? null;
 
+  if (flags.version || flags.v) {
+    const pkg = readOwnPackageJson();
+    console.log(`agent-guardrails v${pkg.version}`);
+    return;
+  }
+
   if (!command || command === "help" || flags.help) {
     printHelp(locale);
     return;
@@ -97,6 +119,26 @@ export async function runCli(argv) {
     return;
   }
 
+  if (command === "start") {
+    await startDaemon(process.cwd(), { locale, foreground: flags.foreground || false });
+    return;
+  }
+
+  if (command === "stop") {
+    stopDaemon(process.cwd(), { locale });
+    return;
+  }
+
+  if (command === "status") {
+    showDaemonStatus(process.cwd(), { locale });
+    return;
+  }
+
+  if (command === "generate-agents" || command === "gen-agents") {
+    await runGenerateAgentsMd({ positional: rest, flags, locale });
+    return;
+  }
+
   const { t } = createTranslator(locale);
   throw new Error(t("cli.unknownCommand", { command }));
 }

package/lib/commands/agents-md.js

@@ -0,0 +1,281 @@
+/**
+ * AGENTS.md Generator
+ *
+ * 基于 Harness Engineering 范式，生成符合 OpenAI 推荐的渐进式文档结构
+ *
+ * OpenAI 团队的 AGENTS.md 结构:
+ * - 精简目录（~100行）
+ * - 渐进式披露
+ * - 指向 docs/ 目录
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import { createTranslator } from "../i18n.js";
+import { ensureDirectory, readConfig } from "../utils.js";
+
+// AGENTS.md 模板
+const AGENTS_MD_TEMPLATE = `# AGENTS.md
+
+> 此文件由 agent-guardrails 自动生成
+> 基于 Harness Engineering 范式，帮助 AI Agent 更好地理解项目
+
+## 项目概述
+
+<!-- 简短描述项目是做什么的 -->
+
+## 快速开始
+
+\`\`\`bash
+# 安装依赖
+npm install
+
+# 运行测试
+npm test
+
+# 启动开发服务器
+npm run dev
+\`\`\`
+
+## 架构约束
+
+### 分层架构
+
+\`\`\`
+┌─────────────────────────────────────────┐
+│              表现层 (UI)                 │
+├─────────────────────────────────────────┤
+│              应用层 (Services)           │
+├─────────────────────────────────────────┤
+│              领域层 (Domain)             │
+├─────────────────────────────────────────┤
+│              基础设施层 (Infra)           │
+└─────────────────────────────────────────┘
+\`\`\`
+
+### 依赖规则
+
+- 上层可以依赖下层
+- 下层不能依赖上层
+- 同层之间尽量独立
+
+## 代码风格
+
+### 命名约定
+
+- 文件名: kebab-case (例: user-service.ts)
+- 类名: PascalCase (例: UserService)
+- 函数名: camelCase (例: getUserById)
+- 常量: UPPER_SNAKE_CASE (例: MAX_RETRY_COUNT)
+
+### 目录结构
+
+\`\`\`
+src/
+├── modules/           # 功能模块
+│   ├── user/
+│   │   ├── user.service.ts
+│   │   ├── user.controller.ts
+│   │   └── user.types.ts
+│   └── ...
+├── shared/            # 共享代码
+│   ├── utils/
+│   └── types/
+└── config/            # 配置文件
+\`\`\`
+
+## 禁止事项
+
+❌ 不要直接修改数据库迁移文件
+❌ 不要跳过测试提交代码
+❌ 不要在 src 外创建新的源代码目录
+❌ 不要使用 any 类型（除非有充分理由）
+
+## 详细文档
+
+更多信息请查看 docs/ 目录：
+
+- [架构设计](./docs/ARCHITECTURE.md)
+- [API 文档](./docs/API.md)
+- [测试指南](./docs/TESTING.md)
+
+---
+*此文件由 agent-guardrails 生成 | Harness Engineering Ready*
+`;
+
+// docs/ARCHITECTURE.md 模板
+const ARCHITECTURE_MD_TEMPLATE = `# 架构设计
+
+## 系统架构
+
+<!-- 描述系统的整体架构 -->
+
+## 模块划分
+
+<!-- 描述主要模块及其职责 -->
+
+## 数据流
+
+<!-- 描述数据如何在系统中流动 -->
+
+## 关键决策
+
+<!-- 记录重要的架构决策及其原因 -->
+
+## 待办事项
+
+<!-- 需要改进的地方 -->
+`;
+
+// docs/TESTING.md 模板
+const TESTING_MD_TEMPLATE = `# 测试指南
+
+## 测试策略
+
+### 单元测试
+
+- 每个模块都应该有对应的单元测试
+- 测试文件放在 \\\`__tests__\\\` 目录或与源文件同级
+- 使用 jest 作为测试框架
+
+\`\`\`bash
+# 运行单元测试
+npm test
+
+# 运行特定测试
+npm test -- user.service.test.ts
+\`\`\`
+
+### 集成测试
+
+- 测试模块之间的交互
+- 使用测试数据库
+
+### E2E 测试
+
+- 测试完整的用户流程
+- 使用 Cypress 或 Playwright
+
+## 测试覆盖率
+
+目标：80% 以上的代码覆盖率
+
+\`\`\`bash
+# 查看覆盖率报告
+npm run test:coverage
+\`\`\`
+
+## Mock 规则
+
+- 外部服务必须 mock
+- 数据库操作使用测试数据库
+- 时间相关的测试使用固定时间
+`;
+
+/**
+ * 生成 AGENTS.md 文件
+ */
+export function generateAgentsMd(options) {
+  const { repoRoot, preset, locale } = options;
+  const t = createTranslator(locale);
+
+  const agentsMdPath = path.join(repoRoot, "AGENTS.md");
+  const docsDir = path.join(repoRoot, "docs");
+
+  // 检查是否已存在
+  if (fs.existsSync(agentsMdPath)) {
+    return {
+      ok: false,
+      reason: "AGENTS.md already exists",
+      path: agentsMdPath
+    };
+  }
+
+  // 创建 docs 目录
+  ensureDirectory(docsDir);
+
+  // 生成 AGENTS.md
+  fs.writeFileSync(agentsMdPath, AGENTS_MD_TEMPLATE, "utf8");
+
+  // 生成 docs/ARCHITECTURE.md
+  const architecturePath = path.join(docsDir, "ARCHITECTURE.md");
+  if (!fs.existsSync(architecturePath)) {
+    fs.writeFileSync(architecturePath, ARCHITECTURE_MD_TEMPLATE, "utf8");
+  }
+
+  // 生成 docs/TESTING.md
+  const testingPath = path.join(docsDir, "TESTING.md");
+  if (!fs.existsSync(testingPath)) {
+    fs.writeFileSync(testingPath, TESTING_MD_TEMPLATE, "utf8");
+  }
+
+  return {
+    ok: true,
+    files: [
+      agentsMdPath,
+      architecturePath,
+      testingPath
+    ],
+    message: "AGENTS.md generated successfully"
+  };
+}
+
+/**
+ * 更新 AGENTS.md
+ */
+export function updateAgentsMd(options) {
+  const { repoRoot, section, content, locale } = options;
+
+  const agentsMdPath = path.join(repoRoot, "AGENTS.md");
+
+  if (!fs.existsSync(agentsMdPath)) {
+    return {
+      ok: false,
+      reason: "AGENTS.md not found. Run 'agent-guardrails generate-agents' first."
+    };
+  }
+
+  const currentContent = fs.readFileSync(agentsMdPath, "utf8");
+
+  // 根据 section 更新对应部分
+  // 这里可以扩展更多 section 的更新逻辑
+
+  return {
+    ok: true,
+    message: "AGENTS.md updated"
+  };
+}
+
+/**
+ * CLI 命令入口
+ */
+export async function runGenerateAgentsMd({ positional, flags, locale = null }) {
+  const repoRoot = positional[0] ? path.resolve(positional[0]) : process.cwd();
+  const preset = flags.preset || "node-service";
+
+  console.log("🔧 Generating AGENTS.md...\n");
+
+  const result = generateAgentsMd({
+    repoRoot,
+    preset,
+    locale: flags.lang || locale
+  });
+
+  if (result.ok) {
+    console.log("✅ AGENTS.md generated successfully!\n");
+    console.log("Files created:");
+    result.files.forEach(file => {
+      console.log(`  - ${path.relative(repoRoot, file)}`);
+    });
+    console.log("\n📖 What's next:");
+    console.log("  1. Review and customize AGENTS.md for your project");
+    console.log("  2. Update docs/ARCHITECTURE.md with your architecture");
+    console.log("  3. Update docs/TESTING.md with your testing strategy");
+    console.log("  4. Point your AI agent to AGENTS.md");
+  } else {
+    console.log(`⚠️  ${result.reason}`);
+    console.log(`   Path: ${result.path}`);
+  }
+
+  return result;
+}

package/lib/commands/check.js

@@ -475,6 +475,11 @@ function printTextResult(result, t, { reviewMode = false } = {}) {
   if (result.failures.length === 0) {
     console.log(`\n${t("check.allPassed")}`);
   }
+
+  if (result.runtime?.costHints?.entries?.length > 0) {
+    console.log(`\n${t("check.costAwareness")}`);
+    console.log(result.runtime.costHints.entries.map((entry) => `- ${t(entry.key, entry.vars)}`).join("\n"));
+  }
 }
 
 function printJsonResult(result) {