agenticworkspace

AgenticWorkspace

将它指向任意代码仓库。它会检测技术栈，在 .workspace/ 目录中生成渐进式上下文和会话交接文件，并通过一条命令安装可用的 Claude Code 适配器。

npx agenticworkspace-cli init

这是一个 v0.1 版本。零安装量、零 GitHub 星标，首次发布。99/99 项 JavaScript 测试和 132/132 项 Python 测试均通过。它只实现下文所述的功能，不多不少。文末还会如实对比其他已在这一领域发挥作用的工具，方便你在运行前判断 AgenticWorkspace 是否值得一试。

目录

• 安装
• 功能
• 快速入门
• CLI 参考
• .workspace/ 目录
• 库 API 参考
• 适配器状态
• 扩展 AgenticWorkspace
• 与 repo-harness 和 harnesskit 的比较
• 是什么以及为什么
• 开发
• 常见问题
• 贡献
• 许可证

安装

AgenticWorkspace 提供两个相互独立、同等重要的软件包，二者实现相同的扫描、生成和适配器工作流，并读写相同结构的 .workspace/ 目录——选择适合你工具链的那个，也可以两个都安装。两者之间没有弃用关系。

# npm -- JavaScript/TypeScript CLI + library (live today, v0.1.3)
npx agenticworkspace-cli init

# PyPI -- Python CLI + library (live today, v0.1.1)
pip install agenticworkspace-cli
agenticworkspace init --path /path/to/your/repo

也可以从源代码安装：

git clone https://github.com/RudrenduPaul/AgenticWorkspace.git
cd AgenticWorkspace/python
pip install -e .
agenticworkspace init --path /path/to/your/repo

如果要反复使用 npm 包，可以全局安装：

npm install -g agenticworkspace-cli
agenticworkspace init

Python 包的 CLI 入口同样是 agenticworkspace（例如 agenticworkspace init --path ./my-app）；Python 专属指南请参阅 python/README.md 和 docs/getting-started.md。

也可以从源代码构建 TypeScript 包：

git clone https://github.com/RudrenduPaul/AgenticWorkspace.git
cd AgenticWorkspace
npm install
npm run build
node dist/agenticworkspace/cli.js init

功能

以下内容均已根据本仓库中的实际源代码验证，并非愿景描述。

• 真实的技术栈检测——检测语言（JavaScript/TypeScript、Python，以及较轻量的 Rust/Go/Ruby 信号）、包管理器（npm/pnpm/yarn）和 monorepo 包数量，数据读取自实际的清单文件（src/agenticworkspace/scan/stack-detector.ts）。
• 默认不破坏现有内容——检查 CLAUDE.md、AGENTS.md、.cursor/rules 和 .github/copilot-instructions.md，且绝不会覆盖这些文件（src/agenticworkspace/scan/config-detector.ts）。
• 检测其他 Agent 记忆工具，但不会触碰它们——查找 .serena/ 目录、GitNexus 风格的配置或 repo-harness 自带的 .ai/harness/ 目录，报告发现的内容，且绝不会读取或写入其中任何内容（src/agenticworkspace/memory-backends/）。
• 真实可用的 Claude Code 适配器——为会话开始、工具调用前和会话结束时生成交接内容编写实际的钩子脚本，并将其接入 .workspace/adapters/claude-code/settings.json（src/agenticworkspace/adapters/claude-code/install.ts）。
• 每个子命令均输出结构化 JSON——init、scan、status、adapter install 和 handoff new 均支持 --json，包括出错时（例如 --path 指向不存在的路径、工作区缺失或适配器尚未实现），因此调用它的 Agent 无需解析人类可读文本，也不必猜测退出码。
• 提供两种有文档说明的插件接口，而非硬编码的流水线——MemoryBackend（src/agenticworkspace/memory-backends/types.ts）和 Adapter（src/agenticworkspace/adapters/types.ts）。添加新工具只需实现一个接口并注册它（分别在各自目录的 registry.ts 中）；无需修改 CLI 或扫描代码。请参阅下文的扩展 AgenticWorkspace。
• 生成钩子时防范 Shell 注入——所有最终嵌入生成的 Shell 脚本中的已扫描值（模块名称、路径）都先经过允许列表和引号检查（src/agenticworkspace/util/sanitize.ts），并由 30 个专门的单元测试覆盖（直接运行测试套件确认，包括参数化的拒绝用例）。
• 恢复部分状态——检测并提示上一次 init 运行遭中断或格式错误的情况（交互模式下提供修复/重置/中止提示；--json 模式下返回带专用退出码的结构化错误），而非静默覆盖或继续运行（src/agenticworkspace/state/partial-state.ts）。

快速开始

在一个只有两个文件的 JavaScript 仓库上实际运行（为便于阅读，目标路径缩短为 /Users/you/my-app；以下每个字段值均为实际输出）：

$ agenticworkspace init --json --path ./my-app

{
  "ok": true,
  "agenticworkspace_version": "0.1.1",
  "scanned_at": "2026-08-04T06:18:25.620Z",
  "target": "/Users/you/my-app",
  "stack": {
    "language": "javascript",
    "package_manager": "npm",
    "monorepo": false,
    "packages": 1
  },
  "existing_config": {
    "claudeMd": false,
    "agentsMd": false,
    "cursorRules": false,
    "copilotInstructions": false,
    "anyDetected": false
  },
  "memory_backends": [
    { "name": "serena", "detected": false, "description": "Serena memory/context tool (.serena/ directory)" },
    { "name": "gitnexus", "detected": false, "description": "GitNexus-style config (.gitnexus/ or gitnexus.config.json)" },
    { "name": "repo-harness", "detected": false, "description": "repo-harness (.ai/harness/ directory) -- detected only, never modified" }
  ],
  "context": { "root_context_kb": 0.6, "budget_kb": 12, "modules": [] },
  "adapters": { "claude_code": { "installed": true, "hook_schema_version": "2026-07-01" } },
  "workspace_dir": "/Users/you/my-app/.workspace"
}

该输出中的 agenticworkspace_version 字段是单独跟踪的版本字符串，与软件包自身的 npm/PyPI 版本无关（两者可能不同步；应将其视为内部架构标记，而非你安装的软件包版本）。

这次运行在磁盘上写入了 7 个实际文件：

.workspace/workspace.json
.workspace/context/root-context.md
.workspace/adapters/claude-code/settings.json
.workspace/adapters/claude-code/adapter-meta.json
.workspace/adapters/claude-code/hooks/session-start.sh
.workspace/adapters/claude-code/hooks/pre-tool-call.sh
.workspace/adapters/claude-code/hooks/session-end-handoff.sh

去掉 --json，即可查看同一次运行的人类可读版本：

$ agenticworkspace init --path ./my-app

AgenticWorkspace v0.1 -- Repo-to-Agent-Workspace Converter
Target: /Users/you/my-app

Scanning repository...
[OK] Stack detected: javascript, npm
[--] No existing agent-config files found
[--] No memory/context tool detected

Writing .workspace/ scaffold...
  .workspace/workspace.json                created
  .workspace/context/root-context.md        created (0.6KB of 12KB budget)
  .workspace/handoff/                       created (empty, ready for first session)

Installing Claude Code adapter...
  .workspace/adapters/claude-code/settings.json         written
  .workspace/adapters/claude-code/hooks/session-start.sh  written
  .workspace/adapters/claude-code/hooks/pre-tool-call.sh  written
  .workspace/adapters/claude-code/hooks/session-end-handoff.sh  written

Workspace ready. Next Claude Code session in this repo will load root-context.md automatically
and write a handoff file on exit.

在同一仓库上检查工作区状态并写入会话交接内容，实际输出如下：

$ agenticworkspace status --path ./my-app

AgenticWorkspace status
Target: /Users/you/my-app
Last scan: 2026-08-04T06:18:25.620Z

Stack: javascript, npm, 1 package(s)
Context budget: 0.6KB of 12KB (0 module block(s))
Handoffs: 0 file(s), most recent: none
Claude Code adapter: installed, schema 2026-07-01, current
Other backends detected: none

$ agenticworkspace handoff new "test session" --path ./my-app

Handoff written: .workspace/handoff/2026-08-04-0618.md

请参阅 docs/usage.gif，查看 handoff new 和 status 一起运行的录屏。

功能

以下所有内容均已根据本仓库中的实际源代码验证，并非尚未实现的设想。

• 真实的技术栈检测——语言（JavaScript/TypeScript、Python，以及针对 Rust/Go/Ruby 的轻量级信号）、包管理器（npm/pnpm/yarn）和 monorepo 包数量，均从实际的清单文件中读取（src/agenticworkspace/scan/stack-detector.ts）。
• 默认不进行破坏性操作——检查 CLAUDE.md、AGENTS.md、.cursor/rules 和 .github/copilot-instructions.md 是否存在，且绝不会覆盖它们（src/agenticworkspace/scan/config-detector.ts）。
• 检测其他 Agent 记忆工具，但不触碰它们——查找 .serena/ 目录、GitNexus 风格的配置，或 repo-harness 自带的 .ai/harness/ 目录，报告发现的内容，且绝不读取或写入其中任何内容（src/agenticworkspace/memory-backends/）。
• 真正可用的 Claude Code 适配器——为会话开始、工具调用前和会话结束交接生成编写实际的钩子脚本，并将其接入 .workspace/adapters/claude-code/settings.json（src/agenticworkspace/adapters/claude-code/install.ts）。
• 每个子命令都支持结构化 JSON 输出——init、scan、status、adapter install 和 handoff new 均支持 --json，包括错误情况（不存在的 --path、缺少工作区、尚未实现的适配器），因此调用它的 Agent 无须解析人类可读文本，也无须猜测退出码。
• 提供两个有文档说明的插件接口，而非硬编码的流水线——MemoryBackend（src/agenticworkspace/memory-backends/types.ts）和 Adapter（src/agenticworkspace/adapters/types.ts）。添加新工具只需实现一个接口并注册它（每个文件夹中的 registry.ts）；无需修改 CLI 或扫描代码。请参阅下文的扩展 AgenticWorkspace。
• 生成钩子时可防止 Shell 注入——每个最终会嵌入生成的 shell 脚本中的扫描值（模块名称、路径），都会先经过允许列表和引号检查（src/agenticworkspace/util/sanitize.ts），并由 30 个专门的单元测试覆盖。
• 部分状态恢复——检测到先前中断或格式错误的 init 运行后，会将其报告出来（交互式修复/重置/中止提示，或在 --json 模式下返回带专用退出码的结构化 JSON 错误），而不是静默覆盖或继续运行（src/agenticworkspace/state/partial-state.ts）。

CLI 参考

每个命令都接受 -p, --path <path>（默认为当前目录）和 --json（输出结构化内容，而不是默认的人类可读内容）。以下参考内容来自本地构建的 agenticworkspace 二进制文件的实际 --help 输出。

命令	说明
agenticworkspace init	扫描代码仓库并写入 .workspace/ 基础结构及 Claude Code 适配器。具备幂等性——可安全重复运行。
agenticworkspace scan	仅检测技术栈和现有 Agent 工具情况。不写入任何内容。
agenticworkspace status	报告工作区健康状况：技术栈、上下文预算使用情况、交接数量、适配器是否过期。
agenticworkspace adapter install <name>	（重新）安装单个适配器的钩子配置，例如 claude-code。对于 codex 或 cursor，返回 adapter_not_implemented。
agenticworkspace handoff new <message>	在 .workspace/handoff/ 下写入新的、带时间戳的会话交接文件。

--json 和人类可读模式下的退出码保持一致，因此脚本无需解析文本即可据此分支。已直接验证：adapter install codex 会以退出码 3 退出，并显示 “NOT YET IMPLEMENTED” 消息；对没有 .workspace/ 的目标运行 status 会以退出码 4 退出。

代码	含义
0	成功
1	一般错误（输入错误、意外的文件系统故障）
2	检测到部分或格式错误的 .workspace/ 状态
3	适配器尚未实现（codex、cursor）
4	未找到 .workspace/（请先运行 init）

MCP 服务

Python 包附带 Model Context Protocol（MCP）服务，因此支持 MCP 的 Agent（Claude Desktop、Claude Code 或任何其他 MCP 客户端）可以将 AgenticWorkspace 作为工具调用，而不必 通过 shell 调用 CLI 并自行解析文本。

pip install "agenticworkspace-cli[mcp]"

将其添加到 MCP 客户端配置中（stdio 传输）：

{
  "mcpServers": {
    "agenticworkspace": {
      "command": "agenticworkspace-mcp"
    }
  }
}

它提供一个工具 run(args: list[str]) -> dict，该工具通过 shell 调用已安装的 agenticworkspace CLI，并传入给定的参数列表，然后返回解析后的结果——所有 子命令（init、scan、status、adapter install、handoff new）都可通过它调用，因此 随着新增子命令，MCP 接口始终与 CLI 保持同步。所有失败情况（缺少二进制文件、超时、非零退出码、 输出无法解析）都会以 {"error": ...} 字典的形式返回，而不会引发异常。调用和结果示例：

run(["scan", "--json", "--path", "/path/to/repo"])
-> {"ok": true, "target": "/path/to/repo", "stack": {"language": "javascript", ...}, ...}

.workspace/ 目录

.workspace/
  workspace.json              manifest: detected stack, adapters installed, schema version
  context/
    root-context.md           progressive root context, budget-targeted (~12KB)
    modules/
      auth.md                 per-module capability block, loaded on demand
      api.md
  handoff/
    2026-07-13-1421.md         one file per session, timestamped
  adapters/
    claude-code/
      settings.json           hook entries wired into Claude Code's settings schema
      hooks/
        session-start.sh       loads root-context.md + relevant module blocks
        pre-tool-call.sh        lightweight guard, extendable per project
        session-end-handoff.sh writes the next handoff/ file automatically

库 API 参考

除了 CLI 二进制文件，两个包还会导出扫描、脚手架和适配器逻辑，供程序化调用。以下签名直接从 源代码中提取。

TypeScript（agenticworkspace-cli，src/agenticworkspace/index.ts）

import {
  detectStack,
  detectExistingConfig,
  memoryBackendRegistry,
  detectAllMemoryBackends,
  adapterRegistry,
  getAdapter,
  runInitEngine,
  readManifest,
  writeManifest,
  sanitizeForShellEmbedding,
  validateAgainstAllowlist,
  shellQuote,
} from "agenticworkspace-cli";

async function detectStack(repoPath: string): Promise<StackDetectionResult>;
async function detectExistingConfig(repoPath: string): Promise<ExistingConfigResult>;
async function runInitEngine(repoPath: string, workspaceDir: string): Promise<InitEngineResult>;
function getAdapter(name: string): Adapter | undefined;
async function readManifest(workspaceDir: string): Promise<WorkspaceManifest | null>;
async function writeManifest(workspaceDir: string, manifest: WorkspaceManifest): Promise<void>;
function sanitizeForShellEmbedding(
  rawValue: unknown,
  warn?: SanitizeWarning,
  options?: SanitizeForShellOptions,
): string | null;
function validateAgainstAllowlist(rawValue: unknown): SanitizeResult;
function shellQuote(value: string): string;

MemoryBackend 和 Adapter 作为 TypeScript 类型导出，供实现新插件的开发者使用 （src/agenticworkspace/memory-backends/types.ts、src/agenticworkspace/adapters/types.ts）。

Python（PyPI 上的 agenticworkspace-cli，python/src/agenticworkspace/__init__.py）

from agenticworkspace import (
    adapter_registry,
    get_adapter,
    memory_backend_registry,
    detect_all_memory_backends,
    Adapter,
    MemoryBackend,
    AGENTICWORKSPACE_VERSION,
)

这里的 Adapter 和 MemoryBackend 是 abc.ABC 类，而不是 TypeScript 接口—— 实现其中一个，并将实例添加到 adapter_registry 或 memory_backend_registry（普通 Python 列表）中，就无需修改 CLI 或扫描代码。该包附带 py.typed 标记，因此类型检查器无需额外配置 即可识别其类型存根。

适配器状态（v0.1）

适配器	状态
Claude Code	已实现，可端到端运行
Codex	已注册，尚未实现
Cursor	已注册，尚未实现

扩展 AgenticWorkspace

AgenticWorkspace 围绕两个插件接口构建，而不是由一个项目包办所有功能：

• MemoryBackend（src/agenticworkspace/memory-backends/types.ts）——检测仓库中是否已接入 记忆/上下文工具。检测必须保持只读。
• Adapter（src/agenticworkspace/adapters/types.ts）——将 .workspace/ 脚手架接入特定的 编码工具：安装、过时检查和易于理解的说明。

为新工具添加支持，意味着实现其中一个接口，并在对应文件夹的 registry.ts 中注册一个 实例；无需修改 CLI 或扫描代码。请参阅 src/agenticworkspace/adapters/codex/ 和 .../cursor/，了解尚未实现的存根的结构（isImplemented: false，并提供真实的 describe() 字符串）， 以及 .../claude-code/ 中完整可用的参考实现。

Python 包（pip install agenticworkspace-cli）通过 abc.ABC 类实现了相同的两个接口，且注册 约定一致（memory_backend_registry / adapter_registry，普通 Python 列表）——两种语言的完整示例请参阅 docs/integrations/custom-plugin.md。

与 repo-harness 和 harnesskit 的比较

面向编码 Agent 的仓库本地上下文和会话交接跟踪并非新概念。在构建本项目之前，我们调查了现有方案。 两个 npm 包涵盖了部分相同领域，它们的当前状态（截至 2026-08-03 检查）比我们对它们的任何自述 都更重要：

	AgenticWorkspace v0.1.3 (npm) / v0.1.1 (PyPI)	repo-harness v0.13.0	harnesskit v0.1.1
npm 活跃度	已发布 3 个版本（0.1.1 -> 0.1.3），创建于 2026-07-15，最近一次发布于 2026-08-04	已发布 46 个版本，创建于 2026-05-28，最近一次发布于 2026-08-03（与本次检查日期相同）	已发布 2 个版本，最近一次发布于 2026-03-20（截至本次检查，已约 4.5 个月未更新）
GitHub	0 个星标、0 个分支（新仓库）	402 个星标、29 个分支，推送时间为 2026-08-03	GitHub 仓库现在返回 404，无法检查源代码
Claude Code 适配器	已端到端实现：真实的 hook 脚本 + settings.json 配置；创建工作区的同一次运行中由 init 完成安装	已实现：~/.claude/settings.json hook 适配器	未验证，无法检查源代码或 README（npm 页面阻止了我们的抓取，GitHub 仓库已消失）
Codex 适配器	已在适配器接口中注册，install() 会抛出“尚未实现”错误——明确的存根，不会静默无操作	已实现：~/.codex/hooks.json 适配器	未验证
Cursor 适配器	已注册，与 Codex 采用同样明确的存根模式	当前 README 中完全没有提及（此前的比较发现架构文档中提到了它；截至本次检查，该引用已消失）	未验证
渐进式上下文加载	以预算为目标的根上下文文件（约 12KB）加上按需加载的模块级能力块	约 12KB 的稳定根上下文，加上仅在实际处理文件时加载的约 1KB 能力契约；由我们未构建的 CodeGraph 结构索引提供支持	未验证
会话交接文件	handoff/ 下每个会话一个带时间戳的文件	.ai/harness/handoff/ 目录，以及从工作流产物派生的 tasks/current.md	未验证
CLI JSON 输出	每个子命令（scan、status、adapter install、handoff）都支持 --json，包括错误路径	至少 --dry-run --json 和 state-snapshot --json 支持 JSON 输出	未验证
无需触碰即可检测其他工具	是：检查 .serena/、类似 GitNexus 的配置以及 repo-harness 自己的 .ai/harness/ 目录，报告发现的内容，绝不读取或写入其中任何内容	未检查——超出我们的审查范围	未验证
插件/扩展模型	文档中定义了两个 TypeScript 接口（MemoryBackend、Adapter）；添加工具只需实现其中一个并注册，无需更改 CLI	仅凭 README 无法验证；需要阅读源代码才能确认	未验证
托管式多仓库控制面板	不存在。不属于此开源 CLI 的规划范围	不存在，仅支持可自托管的文件型工作流	未验证
文档语言	仅英文	英文（主要语言），另有简体中文、日语、法语、西班牙语	未验证

我们能验证的信息来自 npm view、GitHub API 和 repo-harness 自己的 README（直接抓取）。 我们没有安装 repo-harness 并在真实仓库中运行它，因此表中标为“已实现”的内容只是我们读到的 README 声称，并非我们亲自复现验证的结果。 harnesskit 标为“未验证”的内容仍无法验证，因为其 GitHub 仓库已无法访问，npm 页面也阻止了自动抓取；我们不会根据描述字符串猜测工具的功能。（另有一个同名的 PyPI 包 harnesskit，但那是由另一位作者开发的不同且无关的项目——一个用于 LLM 编码 Agent 的模糊字符串替换工具——因此我们没有将它纳入比较。）

自我们上次检查以来，repo-harness 自身的范围有所扩大：其 README 现在重点介绍一个由 ChatGPT 驱动的 MCP 规划 sidecar，并将任务交接给 Codex 执行；此外还包含本表已涵盖的 Claude/Codex hook 适配器。这比“仓库本地上下文和交接跟踪”大得多；在你按项目而非按功能比较这两个工具之前，值得了解这一点。 坦诚地说：就这张表中的几乎所有方面而言，repo-harness 目前都比 AgenticWorkspace 成熟得多。它已经有可用的 Claude Code 适配器和 Codex 适配器，文档也提供了五种语言。它一直在快速迭代（两个多月内发布了 46 个版本）。如果你已经在使用它，而且用得顺手，就没有理由换用其他工具。

我们实际采取的不同做法是：采用插件架构，提供两个小巧且有文档说明的接口（用于检测其他工具的 MemoryBackend，以及用于接入特定编码 Agent 的 Adapter），而不是让一个项目包揽一切；同时加入显式兼容性检查，检测 repo-harness 自己的 .ai/harness/ 目录，并报告检测结果，而不是默默创建重复内容或造成冲突。除此之外，目前这只是一个新推出、尚未经过验证的命令行工具，要与一个更成熟的工具竞争。我们不会粉饰这一点。

还有一件事值得一提：Claude Code 本身现在已提供基于 MEMORY.md 的一方记忆系统和团队记忆存储，以及一个 post-session 生命周期钩子，可用于快照记录未提交的工作。它不会像 AgenticWorkspace 那样扫描仓库的技术栈或安装 Claude Code 专用适配器，但“平台原生提供的功能”和“此类工具带来的额外功能”之间的差距，已经比这一类别刚兴起时更小。在假设这类工具会一直有必要之前，值得持续关注这一变化。

是什么以及为什么

编码 Agent 会在会话结束时失去上下文，而每个仓库都需要先手动设置，Agent 才能有效地在其中工作：要编写什么样的 CLAUDE.md 或 AGENTS.md 文件，如何将未完成的工作交接给下一个会话，以及要接入哪些钩子。这些设置重复又繁琐，很容易出错，而且项目技术栈发生变化后，也很少有人及时更新。

AgenticWorkspace 会自动完成设置中那些机械且与仓库无关的部分：识别仓库使用的技术栈，编写渐进式上下文文件，使其大小控制在令牌预算之内，而不是写入模型所需的整个代码库；并安装真正可用的钩子，让 Claude Code 会话自动生成交接说明，而不是依赖人工记录。它并不试图成为记忆数据库、语义代码索引或托管式仪表板。它是一个脚手架命令行工具：只需写入一次文件，格式便于上述其他工具日后读取或扩展，然后它就会退到一边。

既然 repo-harness 已经存在且更受欢迎（见上方的对比表），为什么还要再做一个？坦诚地说：不是为了取代它。这个项目旨在测试一个范围更窄、优先支持 Claude Code 的同类方案，从第一天起就采用插件架构，将检测逻辑与适配器代码解耦；同时公开说明它与先行工具相比究竟如何。

开发

git clone https://github.com/RudrenduPaul/AgenticWorkspace.git
cd AgenticWorkspace
npm install
npm run build
npm test

截至此版本发布，99 项测试全部通过。提交拉取请求前，请运行 npm run lint、npm run typecheck、npm run test:coverage 和 npm run build——这些与 CI 在 Node 20.x 和 22.x 上运行的步骤相同。

Python 软件包的开发步骤如下：

cd python
python3 -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

截至 Python 软件包首次发布，132 项测试全部通过。有关 Python 专属的开发说明，请参阅 python/README.md。

常见问题

AgenticWorkspace 是什么？与手动编写 CLAUDE.md 文件有何不同？ 它是一个将仓库转换为 Agent 工作区的工具：只需运行一条命令（agenticworkspace init），即可扫描仓库的技术栈、编写渐进式且符合令牌预算的上下文文件，并安装带有实际钩子脚本的 Claude Code 适配器，整个过程一次完成且不会破坏现有内容。它的差异化之处在于，这一过程是自动化且与仓库无关的，而不是让你复制并手动编辑模板；它围绕两个有文档说明的插件接口（MemoryBackend、Adapter）构建，而非采用硬编码的流水线，因此添加新的编码 Agent 适配器或记忆后端，无需修改命令行工具或扫描代码。 安装和平台要求是什么？ npm 包要求 Node.js 20 或更高版本（package.json 中的 "engines": { "node": ">=20.0.0" }）。 Python 包要求 Python 3.9 或更高版本（python/pyproject.toml 中的 requires-python = ">=3.9"），并在 PyPI 上标记为 Operating System :: OS Independent。这两个包都是纯 Node/Python 实现，没有原生或特定操作系统的依赖；日常开发和测试在 macOS 和 Linux 上进行，维护者尚未单独验证 Windows。

这会修改我现有的 CLAUDE.md、AGENTS.md 或 .cursor/rules 吗？ 不会。init 会检查全部四个配置文件（CLAUDE.md、AGENTS.md、.cursor/rules、.github/copilot-instructions.md）并报告检查结果，但绝不会写入或覆盖其中任何文件。

如果我已经在使用 Serena、GitNexus 或 repo-harness，这会与它们冲突吗？ 不会。检测操作仅限读取：AgenticWorkspace 会检查 .serena/、GitNexus 风格的配置以及 repo-harness 的 .ai/harness/ 目录，在 scan/status/init 输出中报告检查结果，但绝不会读取、写入或删除其中的任何内容。

与目前最成熟的替代方案 repo-harness 相比，实际情况如何？ 完整且注明日期的对比请参阅上文的完整对比表。简而言之：目前，repo-harness 在几乎所有可衡量的方面都更加成熟（发布版本更多、GitHub 星标更多、拥有可用的 Codex 适配器、支持五种文档语言，且 MCP 规划与 Codex 执行的范围更广）。AgenticWorkspace 的不同之处在于采用了规模更小的双接口插件架构，并明确以只读方式检查与 repo-harness 自身的 .ai/harness/ 目录是否兼容。如果 repo-harness 已经满足你的需求，那么这张表中没有任何理由让你切换。

如果 init 在执行到一半时中断，会发生什么？ 下次运行 init 时，它会检测遗留的 .init-in-progress 标记，或缺失/格式错误的 workspace.json，然后提示你修复、重置或中止（交互式终端）；或者返回结构化 JSON 错误并以退出代码 2 退出（非交互模式或 --json 模式），而不是悄悄覆盖或继续执行。

为什么 Codex 或 Cursor 适配器还没有实现？ 两者都已在 Adapter 插件接口中注册，isImplemented: false，并提供真实、如实的 describe() 字符串，而非静默空操作。我们优先开发了 Claude Code，因为该仓库自身的工作流就是围绕这个适配器构建和测试的。欢迎贡献代码来实现其中任一适配器，详见扩展 AgenticWorkspace。

有托管仪表板或付费版本吗？ 本仓库中没有。此 CLI 是免费、本地运行且与 MIT 许可证类似（Apache-2.0）的版本。这里没有需要注册使用的托管组件。

这是什么许可证？我可以将其用于商业用途吗？ Apache License 2.0（参见 LICENSE）。该许可证允许商业使用、修改、私下使用和分发，并明确授予专利许可；但须保留许可证和版权声明，且不提供任何保证。

有 Python 版本吗？ 有——这是一个真正的 Python 移植版（并非对 Node 二进制文件的封装），CLI 形式相同，输出的 .workspace/ 相同，MemoryBackend/Adapter 插件契约也相同；此外还提供了可导入的库接口（Adapter 和 MemoryBackend 是 abc.ABC 类）。Python 专属的安装和使用指南请参阅 python/README.md。

贡献

开发环境设置、PR 前检查清单，以及添加新 MemoryBackend 或 Adapter 的具体说明，请参阅 CONTRIBUTING.md。涉及安全的更改（任何涉及生成的 shell 脚本的内容）必须使用其中介绍的共享清理模块。

许可证

Apache 2.0。参见 LICENSE。