开始使用
在 5 分钟内完成 Datarim 配置
给它仓库 URL,让它安装 Datarim;它会遵循 INSTALL.md。智能体的第一步:运行 ./install.sh --project <path>,不带任何答案标志,且在该次运行前不要向你询问任何问题。没有终端时,安装程序会以 STOP 停止,打印六个问题及其默认值和一个一次性答案令牌,并告诉智能体逐字转述这些问题,不推荐任何答案。智能体用你的答案和该令牌重新运行。
# 代码仓库
https://github.com/Arcanada-one/datarim
# 指南原文(网页摘要抓取会丢失大部分内容)
https://raw.githubusercontent.com/Arcanada-one/datarim/v4.12.3/INSTALL.md
1 前置条件
- Python 3.10 或更新版本,以及 git。
- 至少安装并登录一个智能体客户端:Claude Code(
claude)、Codex CLI(codex)、Cursor CLI(cursor-agent或agent)、Google Antigravity(agy)或 MiniMax Code(mcode)。Datarim 不创建客户端账户,也不读取模型提供商的密钥;每个客户端自行登录。 - 项目目录。推荐使用 git 仓库:这样安装程序才能通过
.git/info/exclude隐藏其文件。 - 仅用于 Jev 路由建议:一个 Jev API 密钥,由 Jev API 提供商 TypeSafe(
api.typesafe.ai)签发。你需要每台计算机一个密钥,由该机器上的所有客户端共享。没有密钥时,Jev 仍会运行其本地安全底线;只是缺少路由建议。
2 获取源码
git clone https://github.com/Arcanada-one/datarim.git ~/src/datarim
cd ~/src/datarim
git checkout "$(git describe --tags --abbrev=0 --match 'v*')" # 最新发布标签
保留此检出:update.sh 和 --uninstall 之后会从这里运行,因此请把它放在持久位置,例如 ~/src/datarim,绝不要放在 /tmp,也绝不要放在项目内部。停留在 main 分支也受支持。安装的提交记录在 <project>/.datarim-runtime/installation.json(source_sha)中。要将项目固定到某个发布版本,请在安装或更新前检出该标签(git checkout vX.Y.Z)。Host Jev 拒绝从有未提交更改的检出安装。
共享仓库与报告交付
当队友不使用 Datarim 时,在已应答的安装命令中加上 --team-neutral。安装和更新不会改动根目录的指令文件。如果仍残留旧版受管理的根块,更新会停止,直到手动移除该块。只有 datarim/AGENTS.md、datarim/config.yaml 和 datarim/local/ 对 Git 可见;任务状态保持私有。
delivery:
reports: reports/datarim/{task_id}将以下内容放入 datarim/config.yaml,即可在经审核的项目相对路径下发布 QA 与合规报告。报告副本会与工作副本进行校验。若缺少该键,私有报告仍可供 Datarim 用户使用,工作流会报告一条可见性提示。
你的回复语言、你的项目文档语言
两者默认均为英语。可一次性设置个人偏好,或选择共享与私有项目默认值。项目文档策略优先于个人文档默认值;你的个人回复语言优先于共享对话默认值。原生受管理/安全规则仍然适用。
python3 .datarim-runtime/skills/human-outcome-reporting/scripts/language.py configure --scope user --replies fr --artifacts en
python3 .datarim-runtime/skills/human-outcome-reporting/scripts/language.py resolve --project "$PWD"在项目安装后运行。若需独立报告,请使用已安装技能目录中的辅助脚本,例如 Codex 的 ~/.agents/skills/human-outcome-reporting/scripts/language.py。用户设置位于 $XDG_CONFIG_HOME/datarim/config.yaml,若不存在则回退到 ~/.config/datarim/config.yaml。项目设置使用 datarim/config.yaml 和私有的 datarim/config.local.yaml;普通安装会将 datarim/ 排除在 git 之外;--team-neutral 仅暴露共享配置和本地扩展。
解析时会重新读取偏好设置;无需重新安装。若旧上下文仍然存在,请开启新对话,尤其是在使用 Cursor 会话启动钩子时。安全语言标签无需双语白名单即可接受。固定渲染器标签需要可用的目录;缺少覆盖时使用已披露的英语回退。保留引用的简报、现有正文、代码和机器值。
最近的私有 datarim/config.local.yaml 会选择其自身项目,即使位于祖先框架之下也是如此。格式错误的设置或损坏的私有标记属于错误,而不是成功回退到祖先。使用 configure --scope local --project /absolute/path/to/project 设置私有偏好;请将该文件排除在公开源码之外。
不依赖 Datarim 的 Human Outcome Reporting
4.2.3 主分支从新的签名根开始。保留现有的本地分支和编辑;请使用单独的干净源码克隆,而不是合并新旧历史。 迁移指南.
如果你希望在每个项目中都能获得清晰的智能体报告,而又不想安装框架,请选择此方式。便携技能 0.3.3 已包含在 Datarim 4.4.0 中,也可独立使用。从发布页下载独立 ZIP 及其签名校验和,按发布指南所述进行校验,然后解压归档:
human-outcome-reporting.zip · 下载发布资源
解压前,下载 ZIP、其 .sha256 校验和以及 .cosign.bundle。验证校验和、可信工作流签名和 GitHub 证明;三者都必须成功。验证软件包。
python3 install.py install --agents antigravity,claude,codex,cursor,minimax --dry-run
python3 install.py install --agents antigravity,claude,codex,cursor,minimax
python3 install.py check --agents antigravity,claude,codex,cursor,minimax或者从已检出的发布版本执行:python3 scripts/human_reporting_install.py install --agents antigravity,claude,codex,cursor,minimax。在 macOS 或 Linux 上使用 Python 3.9 或更新版本;可选的报告校验工具需要 Python 3.10 或更新版本。技能目录为 ~/.claude/skills、Codex 的 ~/.agents/skills、~/.cursor/skills、Google Antigravity(agy)的 ~/.gemini/config/skills,以及 MiniMax Code(mcode)的 ~/.minimax/skills。安装器会将技能添加到每个选定的客户端及其原生持久策略:Claude 输出样式、受管理的 Codex AGENTS.md 块、Cursor 会话启动上下文,以及 ~/.gemini/config/hooks.json 中 datarim-human-outcome-reporting 钩子组下的 Antigravity SessionStart 回调。现有的外部规则和钩子会被保留;冲突的已拥有路径会被拒绝。重启客户端并测试新会话。对于 Cursor 和 Antigravity,请开启新对话;恢复现有聊天不会重新运行会话启动钩子。项目特定的 Claude 输出样式可能优先。用户配置适用于此账户;请为另一主机或远程账户单独安装。安装检查只能证明文件和配置,不能证明未来每个回答都会遵守。
0.3.3 版还为受支持的 Codex、Claude Code、Google Antigravity 和 MiniMax Code 客户端注册了同步 SessionStart 回调。它们会在首条进度消息之前读取原生工作目录的当前偏好,包括新启动或恢复之后;偏好变更时无需重新安装。在 Codex 中,使用 /hooks 通过原生信任控制查看新增或变更的钩子定义。安装程序不会授予信任、绕过审批或更改权限设置。现有的外部钩子和安全钩子保持不变。如果钩子不受支持、被禁用或不受信任,已安装文件检查无法建立启动上下文。请检查原生激活情况,然后在新会话中观察首条进度消息、最终回复和产物。
Claude 会在提交提示词之前通过 UserPromptSubmit 刷新偏好,并在工具完成或失败后通过 PostToolUse 和 PostToolUseFailure 刷新偏好。普通进度和工具叙述使用回复语言;可复用笔记使用产物语言。显式的文档语言请求只更改该产物;回复语言请求只更改回复正文。这些同步回调在不改变输出、决策或权限的情况下添加上下文。工具后输入限制为 1 MiB;启动和提示词输入保留 64 KiB 限制。无效或过大的元数据会披露未解析的偏好。工具失败回调不包括权限拒绝、执行前验证失败和取消。上下文传递不保证模型遵循。此安装程序在 Codex 中没有逐轮回调;如果先前的启动上下文仍然存在,请开启新对话。偏好变更无需重新安装;变更钩子安装需要重新进行激活检查。
生成的回调执行当前偏好辅助程序源码,而不是现有的辅助程序字节码缓存。它们保留外部缓存,并且不写入辅助程序字节码。安装程序的 check 验证文件一致性;runtime_behavior、startup_context、per_turn_context 和 post_tool_context 仍为 not_measured。请分别观察实际的首条进度文本、最终回复和已保存文档。
在聊天回复中生成的可复用 Markdown 笔记或文档摘录仍属于产物。其正文和示例使用产物语言;其外部的说明使用回复语言。不会添加未经请求的翻译示例。显式的双语或翻译请求、逐字输入、代码和机器标识符保留其例外,原生权威仍然优先。
对于 Datarim 项目,请安装或更新下方框架;其命令会自动加载相同的报告技能。主机级报告不会在其他项目中激活 Datarim。python3 install.py uninstall --agents antigravity,claude,codex,cursor,minimax 仅移除自有独立产物。
3 先决定
设置涵盖以下六个选择:五个设置和源发布版本。在终端中,安装程序会逐一提示设置(按 Enter 采用默认值),并提醒你选择发布版本。没有终端时(智能体、脚本),全新安装会以 STOP. Nothing was installed. 停止,退出码为 2,且不写入任何内容,包括 --dry-run。它会列出问题及其默认值,告诉智能体逐字转述这些问题且不推荐任何答案,并打印一次性 --answers <token>:有效期为 60 分钟,仅限此项目,成功安装后即失效;每次新的拒绝都会替换它。重新运行需要每个答案(Jev、--client、--permissions)和该令牌。AI 智能体绝不自行选择答案;仅在用户明确要求时才接受默认值。
| # | 问题 | 默认值 |
|---|---|---|
| 1 | 安装 Jev?none / project(仅此项目)/ host(此机器上该用户的所有项目) | none |
| 2 | 你使用哪些客户端:Claude Code、Codex、Cursor、Antigravity、MiniMax Code?每个客户端传入一个 --client(或逗号列表);命令以及在使用 --with-jev 时的钩子仅写入这些客户端。 |
机器上已安装的客户端 |
| 3 | jev* 启动器(每次安装都有)是否应不提示权限地启动客户端?用 --permissions ask 或 --permissions full 回答:全新安装时必填,更新时会记住;之后可用 jev permissions 更改。直接启动客户端不受影响。 |
否(ask) |
| 4 | 现在创建空任务文件 datarim/tasks.md 与 datarim/backlog.md(--init)? |
是 |
| 5 | 是否将每个框架技能暴露给客户端的自动发现(--expose-skills)?这会把它们的描述加入每个会话。 |
否 |
| 6 | 安装最新发布标签,还是 main? |
最新发布标签 |
嵌套 git 仓库:如果项目包含一些嵌套仓库,且 Datarim 应在其中工作,请为每个仓库添加一个 --context <relative/path>。用 find "$PROJECT" -mindepth 2 -name .git -not -path '*/node_modules/*' 找到它们。
4 安装
先设置一次项目路径(绝对路径),然后仅使用项目路径且不带任何答案标志运行安装程序。在此运行之前,智能体不会向用户询问任何内容。
PROJECT=/absolute/path/to/project
./install.sh --project "$PROJECT" # 在终端中提问;否则打印问题、每个答案对应的标志以及一次性令牌
没有终端时:向用户询问打印出的问题,等待答案,然后在一小时内用答案给出的标志(见下文)和 --answers 加上打印的令牌重新运行。先在该次重新运行中加上 --dry-run 查看计划。没有有效令牌时传入的答案标志会被列为已忽略。绝不自行选择答案:Jev 的安全底线无需任何密钥即可工作,因此缺少密钥不是回答“no Jev”的理由。
选项 A — 仅 Datarim(默认)
用户回答“no Jev” → 标志 --without-jev,加上 --client 列表和他们选择的 --permissions 答案。
切勿代表用户传递它:缺少密钥不是跳过 Jev 的理由,其安全底线在没有密钥的情况下也能工作。
选项 B — Datarim 配合项目级 Jev
用户回答“Jev for this project” → 标志 --with-jev,加上 --client 列表和他们选择的 --permissions 答案。
Jev 钩子仅在此项目中为你选择的客户端注册(.claude/settings.local.json、.codex/hooks.json、.cursor/hooks.json、.agents/hooks.json),并在 config/credentials/jev/api-key 创建一个空密钥文件(模式 0600)。不要在已安装 host Jev 的机器上使用此选项:两组钩子都会运行。请改用选项 C。
选项 C — 主机级 Jev,以及此项目中的 Datarim
用户回答“Jev for the whole machine” → 标志 --with-jev --host-jev,加上 --client 列表和 --permissions 答案。仅在这种情况下,先安装 host Jev:
# 仅当用户选择主机级 Jev 时
python3 scripts/jev_host_install.py --client claude --client codex --client cursor \
--datarim-project "$PROJECT" --dry-run
python3 scripts/jev_host_install.py --client claude --client codex --client cursor \
--datarim-project "$PROJECT"
宿主 Jev 按用户安装一次,并应用于该用户打开的每个目录。它会写入 ~/.config/jev/、~/.local/share/jev/、~/.local/state/jev/,启动器 ~/.local/bin/{jev,jevclaude,jevcodex,jevcursor}(该目录必须在 PATH 中),并将其钩子合并到每个所选客户端的用户配置中,同时保留所有现有钩子。--datarim-project 替换宿主的 Datarim 项目列表:之后添加项目时,需再次传入所有项目。密钥文件为 ~/.config/jev/credentials/api-key。
选项 D — Jev 不带 Datarim
python3 scripts/jev_host_install.py --client claude --client codex --client cursor --dry-run
python3 scripts/jev_host_install.py --client claude --client codex --client cursor
同一个宿主安装器,但不带 --datarim-project,也不进行项目安装。详情:单独使用 Jev。
其他安装选项
| --client <name> | claude、codex、cursor、antigravity(agy)、minimax(mcode)或 all;可重复传入或给出逗号分隔列表。只有这些客户端会获得命令文件以及(配合 --with-jev 时)钩子。全新安装时必填;更新时保留。更新时遗漏的客户端会失去其命令文件和 Jev 钩子。 |
| --claude-import / --no-claude-import | 自 4.1 起已弃用:接受但会提示且无效果。Claude Code 原生读取 AGENTS.md;不会创建指令符号链接。 |
| --permissions ask|full | 权限模式答案(问题 3)。全新安装时必填,更新时会被记住。它设置与 jev permissions 相同的开关,作用于项目;若使用宿主 Jev,则作用于宿主。 |
| --answers <token> | 拒绝时打印的一次性令牌。在没有终端的新安装中,需要它与答案一起使用;有效期为 60 分钟,仅限本项目,成功安装后即失效。每次新的拒绝都会替换它。更新不需要它。 |
| --init | 若缺失,则创建 datarim/tasks.md 和 datarim/backlog.md。现有文件会保留。 |
| --expose-skills | 还会将每个框架技能写入 .agents/skills/、.claude/skills/、.cursor/skills/。其描述会加载到每个会话中。 |
| --context <relative/path> | 允许现有的嵌套 git 仓库使用此安装。按仓库重复传入;再次给出时会替换列表;--no-context 会清除它。 |
| --without-jev, --no-host-jev | --without-jev 是全新安装所要求的“不使用 Jev”答案。更新时,它们会关闭已记录的 --with-jev 或 --host-jev;随后 --without-jev 会撤回项目的 Jev 钩子和 jev-config.json;密钥文件保留。 |
| --dry-run | 以 JSON 打印计划;不写入任何内容。在没有终端的新安装中,它会像安装本身一样拒绝,直到获得答案和令牌。 |
仅当用户选择“默认值”时:--without-jev、--client 配合机器上已安装的客户端、--init 和 --permissions ask。
脚本化安装(CI)
没有跳过答案令牌的开关。使用固定、已审核答案的流水线需要两步:第一次运行会拒绝,并在其重运行行上打印令牌;第二次使用相同答案传入该令牌。将 <flags> 替换为已审核的答案标志,两次运行中保持一致:
out="$(./install.sh --project "$PROJECT" <flags> 2>&1)"
token="$(printf '%s\n' "$out" | sed -n 's/.*--answers \([0-9a-f][0-9a-f]*\) .*/\1/p' | tail -n 1)"
[ -n "$token" ] || { printf '%s\n' "$out" >&2; exit 1; }
./install.sh --project "$PROJECT" --answers "$token" <flags>
AI 智能体替人安装 Datarim 时不这样做:它转达首次运行打印的问题,并使用此人的答案。
安装后的报告
每次安装或更新后,安装程序会在围栏代码块内打印其报告行,开头为“将下面的块原样复制到你对用户的回复中(你可以在其后添加自己的文字):”。智能体将整个块原样复制到其回复中,不得改写;其自己的文字可以跟在块后。这些行是:
- 权限模式及其存储文件:状态目录中的
FULL_PERMISSIONS(存在 =full,不存在 =ask;用jev permissions full|ask更改); - 使用 Jev 时,密钥文件路径,并注明 Jev 安全底线无需密钥即可工作;用编辑器粘贴密钥,切勿使用
echo或printf; 切勿放入 .zshrc/.bashrc:JEV_* 或 DATARIM_* 变量(例如 JEV_PERMISSIONS)或密钥;按 shell 或按启动设置它们;- 当项目有 AGENTS.md 时:
AGENTS.md is not modified by the installer; - 使用 Codex 和 Jev 时,如何接受 Codex 的钩子;使用 Codex 或 Cursor 时,
.agents/skills/dr-*/.cursor/skills/dr-*是为它们打包的/dr-*命令,而非额外的框架技能。
安装是项目本地的:框架的固定快照会放入 .datarim-runtime/,/dr-* 命令会放到各客户端查找的位置(Claude Code → .claude/commands/,Codex 和 Antigravity → .agents/skills/,Cursor → .cursor/skills/,MiniMax → .minimax/skills/),并且它写入的所有内容都会通过 .git/info/exclude 从 git status 中隐藏。它不会触碰你的主目录、shell 启动文件、AGENTS.md 或 .gitignore。自 4.1 起,Claude Code 原生读取 AGENTS.md;安装器从不创建 CLAUDE.md。各客户端详情:运行时。
5 Jev 密钥、权限模式和设置
Jev 是可选的。它增加一个确定性的安全底线——一个拒绝破坏性 shell 命令的钩子,无需密钥或网络——并且,使用 API 密钥时,提供模型层级路由建议。该建议只是建议:它不会切换正在运行的模型,也不授予任何权限。
Jev 密钥的放置位置
在编辑器中打开你安装的密钥文件,将密钥粘贴到一行,保存。该文件已存在且权限为 0600;请保持如此。--with-jev 安装会打印确切路径。
| 安装 | 密钥文件 |
|---|---|
| 项目 Jev(选项 B) | <project>/config/credentials/jev/api-key |
| 主机 Jev(选项 C 或 D) | ~/.config/jev/credentials/api-key |
$EDITOR ~/.config/jev/credentials/api-key # 主机 Jev;项目 Jev:config/credentials/jev/api-key
- 每台计算机一个密钥,由其所有客户端共享;每台计算机使用不同的密钥。
- 切勿用
echo或printf将密钥写入文件:该命令会进入你的 shell 历史记录。切勿将密钥放入提交、设置文件或聊天中。 export TYPESAFE_API_KEY=...不起作用:启动器和钩子会移除该变量,只读取文件。- 使用主机 Jev 时,项目自己的密钥文件保持为空且不被读取;这是正确的。
权限模式(仅 Jev 启动器)
jev permissions # 显示当前模式
jev permissions full # jev* 启动器启动客户端时不显示权限提示
jev permissions ask # 回到客户端自己的提示(默认)
full 会为通过 jev、jevclaude、jevcodex、jevcursor、jevagy、jevminimax 的启动添加 --dangerously-skip-permissions(Claude Code 和 Antigravity)、--dangerously-bypass-approvals-and-sandbox(Codex)或 --force --approve-mcps(Cursor)或 exec --permission full(MiniMax),除非你传入自己的权限选项。安装器的 --permissions ask|full 答案会设置相同的开关。它按项目(项目安装)或按宿主(宿主 Jev)存储。安全底线在 full 模式下仍会运行。直接启动 claude、codex、cursor-agent 或 agy 不受影响。jev off / jev on 会停止和恢复 API 调用;无论哪种方式,安全底线都会继续运行。
配置与密钥
此处没有任何内容会被提交:项目路径由 .git/info/exclude 隐藏,宿主路径位于你的主目录中。下面的环境变量按 shell 或按启动设置,绝不要放在 .zshrc、.bashrc 或其他启动文件中:例如在那里设置 JEV_PERMISSIONS=full 会为每次 jev* 启动关闭权限提示。持久选择有自己的开关:jev permissions、jev on / jev off 以及设置文件。读取每个设置的代码在 INSTALL.md 中列出。
| 设置项 | 位置 | 是否必需 | 默认值 |
|---|---|---|---|
| Jev API 密钥(项目级 Jev) | 文件 <project>/config/credentials/jev/api-key,权限模式 0600 |
仅用于路由建议 | 创建时为空 |
| Jev API 密钥(主机级 Jev) | 文件 ~/.config/jev/credentials/api-key,权限模式 0600 |
仅用于路由建议 | 创建时为空 |
| Jev 设置(项目级) | <project>/.datarim-runtime/jev-config.json:端点、超时、重试、路由模式、钩子开关、遥测 |
否 | 从 plugins/dr-jev-control/config/jev-control.json 复制 |
| Jev 设置(主机级) | ~/.config/jev/config.json,包含 datarim_projects(允许使用 Datarim 的项目) |
否 | 相同的默认值;api.base_url 必须保持为 https://api.typesafe.ai/v1/systemone |
| 开关 | jev off / jev on:在 .datarim-runtime/state/jev/ 或 ~/.local/state/jev/ 中创建 DISABLED 文件 |
否 | 开启 |
| 权限模式 | jev permissions full|ask:同一状态目录下的文件 FULL_PERMISSIONS;环境变量 JEV_PERMISSIONS=full|ask 可在单次启动时覆盖该设置 |
否 | ask |
| 为某个 shell 禁用 Jev 建议 | 环境变量 JEV_DISABLE=1 或 DATARIM_JEV_DISABLE=1(安全底线仍会运行) |
否 | 未设置 |
| 按 Jev 层级指定 Codex 模型 | 环境变量 DATARIM_CODEX_MODEL_HAIKU、_SONNET、_OPUS |
否 | Codex 账户默认值,层级映射为 effort |
| 按 Jev 层级指定 Antigravity 模型 | 环境变量 DATARIM_ANTIGRAVITY_MODEL_HAIKU、_SONNET、_OPUS |
否 | Antigravity 账户默认值,层级映射为 --effort |
| 按 Jev 层级指定 Cursor 模型 | 环境变量 DATARIM_CURSOR_MODEL_HAIKU、_SONNET、_OPUS |
否 | Cursor 默认模型 |
| 客户端可执行文件 | 环境变量 CLAUDE_BIN、CODEX_BIN、CURSOR_BIN、ANTIGRAVITY_BIN(或 AGY_BIN) |
否 | PATH 中的 claude、codex、cursor-agent(或 agent)、agy 或 mcode |
| 按 Jev 层级指定 MiniMax 模型 | 环境变量 DATARIM_MINIMAX_MODEL_HAIKU、_SONNET、_OPUS |
否 | MiniMax 账户默认值;设置覆盖时传入 --model |
| Codex 自动重新信任 | 环境变量 JEV_NO_AUTO_TRUST=1 会阻止 jevcodex(宿主 Jev)重新向 Jev 自身的钩子授予 Codex 信任 |
否 | 未设置 |
| 执行主机映射 | 环境变量 DATARIM_EXEC_HOSTS_MAP,一个 YAML 映射,指明哪台机器可以为某个工作区运行任务 |
否 | $HOME/.claude/local/config/execution-hosts.yml;映射缺失表示跳过该检查 |
由入口点设置,切勿手动设置:DATARIM_RUNTIME(由 source .datarim-runtime/activate.sh 设置,连同 PATH),以及 DATARIM_ROOT、DATARIM_PROJECT_ROOT、DATARIM_JEV_CONFIG、DATARIM_JEV_HOME、DATARIM_JEV_STATE、TYPESAFE_API_KEY_FILE、JEV_STATE_DIR、JEV_HOST_STATE(由 jev* 和钩子设置)。模型提供商密钥(ANTHROPIC_API_KEY、OPENAI_API_KEY 等)不会被安装器、Datarim 的命令或 Jev 读取;你的客户端保留自己的登录方式。
6 验证
cd "$PROJECT"
git status --short # 预期:Datarim 无任何输出
source .datarim-runtime/activate.sh # 仅当前 shell
jev doctor --agent=claude # 或 --agent=codex / --agent=cursor / --agent=antigravity / --agent=minimax
预期的 jev doctor 输出(JSON),退出码 0:
"scope": "project"(或配合--host-jev使用"host"),"datarim_enabled": true;"findings": []— 一条 finding 会指明缺失项(例如claude: executable missing,或cursor: Jev hook file missing (...)),并使退出码为1。不带--agent时,doctor 会检查全部四个客户端,因此你未使用的客户端也会成为一条 finding;"hook_clients"— 本次安装为其注册了 Jev 钩子的客户端;"config_path"— 正在使用的 Jev 设置文件(.datarim-runtime/jev-config.json,或使用宿主 Jev 时的~/.config/jev/config.json);无 Jev 时为null;"native_agents_live"— 按客户端列出,一旦账本中存有来自该客户端的hook_delivery记录,便显示"state": "live"及投递次数和最后投递时间;在该客户端运行钩子之前为not_measured(附带原因)。当注册了多个客户端时,会列出所有已注册客户端,而不仅是--agent指定的那个;无投递的客户端显示“尚无投递”;"key_ready": false,直到你添加密钥(true 仅表示文件非空,并不表示密钥有效);"api": "not_measured"— 离线 doctor 不发起网络调用;这既不是通过也不是失败;"source_sha"— 你安装的提交。
添加 Jev 密钥后,jev doctor --api 应以退出码 0 退出,并输出 "api": {"ok": true, "model": "...", ...};缺少密钥会给出 "reason": "key missing" 和退出码 1。
无需密钥的检查
安全底线,已安装 Jev。在项目中运行;破坏性命令只是 JSON 载荷中的文本,不会被执行:
printf '{"tool_name":"Bash","tool_input":{"command":"rm -rf /"},"cwd":"%s","session_id":"check"}' "$PWD" \
| python3 .datarim-runtime/scripts/jev_hook.py claude PreToolUse # 项目 Jev
# 宿主 Jev:将同一载荷通过管道传入 ~/.local/share/jev/bin/jev-hook claude PreToolUse
预期:"permissionDecision": "deny",原因为 Jev deterministic safety floor: recursive delete of a protected path。
| 问题 | 检查 | 预期 |
|---|---|---|
| 客户端会调用这些钩子吗? | 在项目中使用某个客户端进行一次简短会话,然后运行 tail -n 3 .datarim-runtime/state/jev/ledger.jsonl |
记录中会包含指明该客户端的 hook_delivery 记录。Floor 拒绝不会被记录。宿主 Jev 将其账本保存在 ~/.local/state/jev/projects/ 下。 |
| Jev 是否已正确安装并限定作用域? | jev doctor --agent=<client> |
上述字段;该会话之后,native_agents_live 会将该客户端显示为 live |
| 任务文件格式是否正确? | bash .datarim-runtime/scripts/datarim-doctor.sh --root="$PWD",或在客户端中运行 /dr-doctor |
OK: datarim/ structure compliant |
jev doctor 针对 Jev 给出答案(客户端、钩子注册、密钥文件、作用域、Codex 信任、钩子投递);datarim-doctor.sh 和 /dr-doctor 仅针对 datarim/ 任务文件的结构给出答案。
使用 Jev 和 Codex 时,首次 Codex 会话会询问两次:先信任工作目录,然后 Hooks need review → Trust all and continue。拒绝是静默的:Codex 仍会将钩子列为活动状态,但从不运行它们。jev doctor --agent=codex 会根据 Codex 存储在 ~/.codex/config.toml 中的授权,将 codex_hook_trust 报告为 trusted、untrusted 或 not_measured。
宿主 Jev:针对 ~/.codex/hooks.json 中的钩子。如果其他工具重写了该文件,jev trust 只会重新授予对 Jev 自身钩子的信任;jevcodex 会自动执行此操作,除非设置了 JEV_NO_AUTO_TRUST=1。项目 Jev:针对 <project>/.codex/hooks.json 中的钩子;在项目内运行 jev trust 会重新授予对恰好这些钩子的信任,而 jevcodex 不会自动执行此操作。更改钩子命令的安装(例如解释器路径)会使 Codex 将这些钩子报告为已更改;jev trust 或 Codex 提示会再次批准它们。
7 更新
cd ~/src/datarim
git fetch --tags origin
git checkout "$(git describe --tags --abbrev=0 --match 'v*' origin/main)" # 或:git checkout main && git pull
./update.sh --project "$PROJECT" # 安装时所选的选项会被记住
update.sh 以单个事务运行同一个安装程序:先检查每个文件,拒绝覆盖你编辑过的任何内容,失败时回滚。
你的安装选择会被记住。 --with-jev、--host-jev、--context、--client、--expose-skills 会记录在 .datarim-runtime/installation.json 中,因此直接运行 update.sh --project 会保留它们,权限模式也保持不变。仅在需要更改时才传入选项:--without-jev 撤回项目的 Jev 钩子和 jev-config.json(密钥文件保留),--no-host-jev 恢复为项目钩子,--no-context 撤回嵌套仓库,--client 设置新的客户端列表。4.0 之前的安装没有记录客户端列表,会保留全部三个。
更新时保留:datarim/、config/credentials/、.datarim-runtime/state/(账本、开关和权限开关),以及 Jev 保持开启时的 .datarim-runtime/jev-config.json。.datarim-runtime/ 内的其他内容都会被替换,包括 .datarim-runtime/local/ 下的插件链接:更新后请运行 /dr-plugin sync。先前的运行时保留在 .datarim-runtime-previous/,更早的保留在 .datarim-runtime-backups/。主机 Jev:从更新后的检出目录重新运行 scripts/jev_host_install.py,使用相同的 --client 和 --datarim-project 选项;Codex 会保留其信任,因为钩子命令指向一个稳定的入口点。
~/.claude/{agents,skills,commands,templates,scripts,tests,dev-tools}(以及 Codex 和 Cursor 的对应目录)下解析到你的 Datarim 检出目录的链接,然后按上述方式逐项目安装。3.0 之前安装的项目会在其 AGENTS.md 中追加一段内容,并在 .gitignore 中追加规则;下一次安装或更新会移除这两者,并保持这些文件的其余部分不变。8 卸载
~/src/datarim/install.sh --project "$PROJECT" --uninstall --dry-run
~/src/datarim/install.sh --project "$PROJECT" --uninstall
此操作会将安装更改过的文件恢复为安装前的内容,移除它添加的命令文件和钩子条目,并将运行时移动到 .datarim-uninstalled/。任务状态(datarim/)、密钥(config/credentials/)和运行时备份会保留,仍对 git 隐藏;不再需要时请自行删除。当 .datarim-uninstalled/ 存在时,第二次卸载会被拒绝。安装后你编辑过的文件会阻止卸载,直到你协调它们。
主机 Jev 没有卸载程序。jev off 会停止主机上所有 Jev API 调用。要移除它,请从客户端配置中删除 Jev 条目(命令中引用 ~/.local/share/jev/bin/jev-hook 的条目),然后删除 ~/.local/bin/{jev,jevclaude,jevcodex,jevcursor}、~/.local/share/jev/、~/.config/jev/(存放密钥)和 ~/.local/state/jev/(存放安装备份)。
出问题了?INSTALL.md 中的故障排除表将每条安装程序消息映射到其原因和修复方法。
9 你的第一个任务
前往已安装 Datarim 的项目并启动你的智能体(在 Codex、Cursor、Antigravity 和 MiniMax Code 中,让它运行 dr-init 技能):
cd /path/to/your/project
claude
# 在 Claude Code 中:
/dr-init 为设置页面添加深色模式切换
Datarim 会分析你的请求,确定复杂度(L1-L4),并在 datarim/ 中创建任务跟踪。
自 v2.7.0 起:当你的描述与待办列表中已存在的条目主题重叠时,步骤 2.5b 会给出软性提示,避免你为同一项工作创建第二个 ID。此提示不阻塞流程——由你在继续之前决定 重复 / 细化范围 / 正交。
10 遵循流水线
并非每个任务都需要全部 8 个阶段。Datarim 按复杂度进行路由:
11 常用命令
/dr-help
列出全部命令
/dr-init
开始新任务
/dr-prd
需求 + 上下文调研
/dr-plan
详细实现计划
/dr-do
按计划实现(TDD)
/dr-qa
质量检查
/dr-verify
按需独立三层验证
/dr-archive
反思、归档并更新待办
/dr-write
创建内容
/dr-publish
发布到各平台
/dr-status
当前任务状态
12 项目结构
执行 /dr-init 后,你的项目将获得:
your-project/
├── .datarim-runtime/ # 此修订版本的框架(不纳入 git)
├── datarim/ # 工作流状态(不纳入 git)
│ ├── tasks.md # 进行中的任务
│ ├── backlog.md # 待处理条目
│ ├── activeContext.md # 当前焦点
│ ├── tasks/ # 任务文档
│ └── ... # prd/, creative/, reflection/, qa/, reports/, history/
└── documentation/
└── archive/ # 已完成的任务(请提交)
├── web/
├── infrastructure/
└── ...
datarim/ 是你的本地工作流;安装过程会通过 .git/info/exclude 将其与 .datarim-runtime/ 一并隐藏,而不会修改共享的 .gitignore。documentation/archive/ 是项目历史——请提交到 git。
Init-task 文件与问答日志(v2.9.0):/dr-init 会将你的原始提示逐字保存到 datarim/tasks/{ID}-init-task.md。此后每次澄清——智能体的提问与你的回答——都会以结构化的「Q&A by /dr-<stage>」块自动追加到该文件的 Append-log 中。若你未作答,智能体将依据最佳实践自主决策,并记录至少 50 字符的理由;评审阶段会对照实现逐一核验每项自主决策。
13 插件(v1.23.0+)
通过 /dr-plugin 以可选插件扩展 Datarim。每个插件是一个目录,包含 plugin.yaml 以及 {skills,agents,commands,templates}/ 子目录。启用后会在项目内的 .datarim-runtime/local/<cat>/<plugin-id>/ 下创建符号链接。
/dr-plugin list # 活动集
/dr-plugin enable /path/to/my-plugin # 启用本地插件
/dr-plugin disable my-plugin # 禁用
/dr-plugin sync # 协调运行时 ↔ 清单
/dr-plugin doctor [--fix] # 10 health checks
活动集清单:datarim/enabled-plugins.md。每次启用前均进行变更前快照/回滚。完整参考 — 命令页面 →
内置插件:dr-orchestrate、dr-jev-control、tdd-enforcement、dr-fleet-evolution 以及(v3.1.0+)controller-continuation —— 面向运行自有外部控制器的项目所提供的 /dr-continue-checkpoint worker 入口,仅限 Linux。它不是核心命令:核心仍保持 29 条命令。
14 网络暴露基线(v1.24.0+)
网络绑定目标的默认安全契约:docker-compose 端口、redis.conf 的 bind、postgresql.conf 的 listen_addresses、systemd .socket。默认公开即默认失守;新增的 network-exposure-baseline.md 技能以 TTL 受限的豁免机制将分层模型正式化。
127.0.0.1、::1)—— 允许;开发用 compose 的标准做法。100.64.0.0/10 —— 允许(按定义仅限网格内)。0.0.0.0、[::]、公网 IP —— 要求内联 x-exposure-justification + x-exposure-expires(≤90 天)。本地 pre-commit 检查:
dev-tools/network-exposure-check.sh \
--compose docker-compose.yml \
--redis-conf redis.conf \
--postgres-conf postgresql.conf
# exit 0 — clean; exit 1 — violation
.github/workflows/ci.yml 中的可复用 CI 工作流:
jobs:
network-exposure:
uses: Arcanada-one/datarim/.github/workflows/network-exposure-lint.yml@<40-hex-commit>
with:
compose_paths: docker-compose.yml docker-compose.prod.yml
datarim_ref: '<same-40-hex-commit>'
流水线命令(/dr-prd、/dr-plan、/dr-do、/dr-archive)在网络表面变更时自动加载该技能。分层门禁:P0 / 安全 / 基础设施 / 框架加固类任务 → hard_block;其余 → advisory_warn,可由操作员覆盖。
15 自主智能体运行规则(v2.6.0+)
当操作员需求不完整、复杂或含糊时,智能体不得停滞或进行不必要的升级上报。八条规范规则(FB-1..FB-8)在最高指令法则 1-5 之下定义自主行为。该授权位于使用方生态的 AGENTS.md 中(规范文本 + 审计标记);Datarim 仅提供机器可读的契约块。
机器可读的策略块:
dev-tools/rules/fb-rules.yaml
# rules: 8 × {rule_id, enforcement_layer, tier, default_action,
# reversibility_required, audit_required, conflicts_with_law}
# hard_gated_actions: [prod_deploy, secret_rotation, irreversible_db_op,
# public_communication, finance_action, legal_action,
# force_push_main, git_history_delete, multi_user_visible_action,
# content_consilium_publish]
层级:最高指令(法则 1-5)> 自主智能体运行规则 > AAL 授权 > 项目特定授权。无论 FB-5 如何,hard_gated_actions 永不自动执行。加载器:dev-tools/fb-policy-loader.sh § load_fb_policy() / load_fb_hard_gates()(核心;dr-orchestrate 插件通过一层薄垫片调用它)。
D 文档:Diátaxis 分类法
每个由 Datarim 管理的仓库和产品站点都必须按照 Diátaxis 组织其文档:四个正交类别——tutorials/(学习)、how-to/(解决问题)、reference/(查阅)、explanation/(理解)。
documentation/
├── tutorials/ # learning-oriented
├── how-to/ # problem-solving (testing, deployment, gotchas)
├── reference/ # information-oriented (architecture, api, cli)
└── explanation/ # understanding-oriented (design, concepts)
封闭集合:faq、glossary、troubleshooting、examples、overview、samples——可映射,但绝不作为独立的顶层类型。与技术栈无关——SSG/CMS 的选择因项目而异。/dr-init create project 会在 documentation/ 下搭建此布局;/dr-optimize 会给出软性漂移警告,硬性 CI 门禁暂缓实施。