imMamdouhaboammar/dokion

Problem to project: Why I built Dokion

Dokion A user-directed hardening runtime that executes an explicit software repair playbook across coding agents.

Recurring problem Hardening work drifts when agents choose tools, reorder checks, or claim readiness without durable evidence and bounded rollback.	Practical goal Let the user own the hardening playbook while Dokion validates execution, journals evidence, verifies repairs, and restores rejected changes.
Built for Developers using Claude Code, Codex, Gemini CLI, and shell tools for repeatable software hardening.	Search terms software hardening agent · AI repair validation · user directed agent runtime · evidence based code repair

Daily build pulse

• 23 commits landed: docs: add dynamic project story card; security: add repository threat model.
• 29 pull requests updated, led by #29: docs: add dynamic project story card.
• Daily summary covers 52 public activity items from the last 7 days.

## 当前状态 Runtime 基线：已实现 M0-M6。 生产环境强化待办事项：进行中。 Dokion 是一个可执行的 Bun CLI，具备跨 Agent 打包、对抗性修复验证、干净安装复现、包验证以及受保护的 Bun-only 发布 pipeline。已审计的基线记录在 [`docs/architecture/current-baseline.md`](docs/architecture/current-baseline.md) 中，当前的生产环境待办事项记录在 [100 次提交的实施计划](docs/superpowers/plans/2026-07-25-production-grade-bounded-autopilot-backlog.md)中。此状态并未断言已达到普遍的生产环境就绪状态。 支持声明按照宿主机、交付模式和 Agent 适配器在[支持与兼容性矩阵](docs/compatibility.md)中进行了分类。交叉编译和打包并不等同于原生宿主机执行。 已实现： - M0：schemas、一致性测试和 CI 验证 - M1：不可变的 playbook 加载和 SHA-256 突变检测 - M2：有序执行、状态日志记录、证据捕获、报告和恢复 - M3：规范化发现、审批记录、声明的修复和验证 - M4：基于快照的对抗性修复验证、就绪门禁和精确回滚 - M5：一个标准的强化技能、Claude Code/Codex/Gemini CLI 适配器、平台检测和可靠的降级报告 - M6：内嵌 runtime 资产、精确的 tarball 检查、干净的 Bun 安装测试、官方的 Gemini 验证、跨平台二进制文件和受保护的发布自动化 规范仍然是预期行为的权威。Runtime 和发布声明仅限于由代码和 CI 覆盖的行为。 ## 权限模型 Dokion 不决定应该运行哪个能力。 `dokion.json` 是一个非活跃的目录。它描述了已知的技能、工具、插件、循环和策略。目录中的条目不会仅仅因为被列出就执行。 `.dokion/playbook.json` 是唯一的执行权威。用户拥有： - 能力选择 - 执行顺序 - 权限 - 审批策略 - 重试和停止规则 - 验证命令 - 发布门禁 Dokion 可以验证、执行、记录日志、核实、解释差距并编写非活跃的建议。它不能自主选择、安装、替换、重新排序、升级或启用某个能力。 ## 跨 Agent 模型 强化工作流只需编写一次： ``` skills/dokion-hardening/SKILL.md ``` 平台包是轻量级的适配器： ``` Claude Code .claude-plugin/plugin.json .claude/skills/dokion/SKILL.md hooks/hooks.json scripts/claude-playbook-guard.ts Codex AGENTS.md .codex/AGENTS.md .agents/skills/dokion-hardening/SKILL.md Gemini CLI gemini-extension.json GEMINI.md commands/dokion/run.toml commands/dokion/status.toml ``` 适配器转换发现、打包、命令、上下文和 hooks。它们不会创建第二个工作流，也没有权限更改 playbook。 ## 平台保证与降级 Dokion 保守地检测当前活动的 agent。`DOKION_AGENT` 是明确的权威。当缺少明确值时，可以使用无歧义的平台环境标记。如果出现相互矛盾的证据，则会归为 `other`，而不是盲目猜测。 只有在拥有明确证据时才会记录保证： ``` DOKION_GUARANTEE_HOOK_ENFORCEMENT=1 DOKION_GUARANTEE_SUBAGENT_ISOLATION=1 DOKION_GUARANTEE_PARALLEL_WRITES=1 DOKION_GUARANTEE_WORKTREE_ISOLATION=1 ``` 缺失的证据会存储在 `.dokion/state.json` 中，并在 `HARDENING.md` 中显示为一项或多项降级： - `NO_HOOK_ENFORCEMENT` - `NO_SUBAGENT_ISOLATION` - `NO_PARALLEL_WRITES` - `NO_WORKTREE_ISOLATION` 如果没有证据，Dokion 绝不会将具有不同能力的 agent 视为等同。 ## Claude Code 完整性防护 Claude Code 插件为 Bash、Edit、Write 和 NotebookEdit 注册了一个 `PreToolUse` 防护。在 `RUNNING` 或 `AWAITING_USER` 期间，它会比较当前的 playbook 摘要与存储在 `.dokion/state.json` 中的摘要。 对于缺失 playbook、无效摘要、非规范化路径、symlink 或内容突变，该防护将处于默认拒绝（失败即阻止）状态。Terminal 运行期间不会持续阻止用户的工具。 ## 修复验证 每次修复都会接收到在声明的修复命令执行前一刻捕获的 repository 快照。 验证器会将该快照与修复后的目录树进行比较，并检查： - 已跟踪和未跟踪的非忽略文件 - 添加、修改和删除的路径 - 在声明的写入范围之外的编辑 - 新添加的抑制指令 - 删除的测试和添加的跳过指令 - diff 大小限制 - 是否确实添加或修改了必需的回归测试 历史未更改的测试不能满足 `require_regression_test`。 当修复、对抗性验证或验证命令失败时，Dokion 会为该发现恢复到确切的修复前状态。这样既保留了修复前已存在的无关脏工作，又移除了被拒绝的修复所创建的文件。 被忽略的未跟踪目录树不在修复快照的覆盖范围内。在实现有边界的忽略文件策略之前，此边界必须保持可见。 ## 分发证明 Dokion 验证由 `bun pm pack` 生成的确切归档，而不仅仅是 repository 的源代码树。 包门禁检查： - 必需的 runtime、schema、技能、适配器和文档文件 - 禁止的测试、状态、诊断、lockfiles、生成的输出和凭证文件 - 常见的密钥签名和私有本地路径 - 包、Gemini 扩展和发布标签的版本同步 - 规范技能封装器和适配器清单结构 干净安装的冒烟测试会将 tarball 安装到一个空的 Bun 项目中，并通过 `node_modules/.bin/dokion` 运行已安装的 CLI。它验证了内嵌的 schemas 和非活跃的内置目录在没有 Dokion repository 根目录访问权限的情况下也能正常工作。 `dokion init` 仅创建状态和报告路径。它不会静默地创建活动的 playbook，也不会将内置目录复制到用户的项目中。 ## 发布模型 标签工作流在发布前会重新运行所有的 runtime、契约、分发、干净安装和 Gemini 扩展门禁。 发布产物包括： - Linux x64 基线二进制文件 - Linux ARM64 二进制文件 - macOS ARM64 二进制文件 - macOS x64 二进制文件 - Windows x64 基线二进制文件 - Bun 包 tarball - SHA-256 校验和 注册表发布使用受保护的 `npm-release` GitHub 环境中的 `bun publish`。Token 仅通过 `NPM_CONFIG_TOKEN` 提供。 Dokion 不宣称支持 npm OIDC trusted publishing，因为自动交换目前需要 npm CLI，这与 repository 的 Bun-only 包操作规则相冲突。参见 [docs/RELEASING.md](docs/RELEASING.md)。 ## Runtime 布局 ``` HARDENING.md .dokion/ playbook.json state.json events.ndjson findings/ evidence/ reports/ runs/ ``` `HARDENING.md` 是人类可读的报告。`.dokion/state.json` 是用于恢复和重试的机器状态。 ## CLI ``` Observe dokion inspect dokion doctor dokion status dokion findings dokion report dokion tools list dokion skills list dokion plugins list dokion loops list Configure dokion init dokion plan dokion validate dokion validate --catalog-only Execute dokion run dokion resume dokion verify dokion approve --by [--notes ] dokion reject --by [--notes ] ``` 没有 `dokion install` 命令。 ## 安装说明 全局 CLI： ``` bun add --global dokion ``` Repository 本地 CLI： ``` bun add --dev dokion ``` ## 开发环境设置 要求： - Bun 1.3.14 或更新版本 - 带有 `jsonschema` 的 Python 3，用于 schema 一致性开发检查 - Git - 系统 `tar`，用于精确的包归档检查 ``` bun install --frozen-lockfile python3 -m pip install jsonschema bun test bun run typecheck bun run validate:contracts bun run build bun run validate:distribution bun run smoke:package ``` ## 最小化项目流程 初始化 Dokion 拥有的状态： ``` dokion init ``` 自行创建 `.dokion/playbook.json`，或复制并编辑参考 playbook。将每个占位符摘要替换为不可变的引用。 在执行前进行验证： ``` dokion validate ``` 预览确切的只读执行计划： ``` dokion plan ``` 运行已批准的 playbook： ``` dokion run ``` 当某个步骤暂停以等待批准时： ``` dokion approve finding:DK-APPSEC-001 --by mamdouh --notes "Approved scoped repair" dokion resume ``` ## 证据规则 只有当声明的命令成功退出且其输出被作为证据存储时，步骤才算成功。 一个发现要达到 `VERIFIED` 状态，必须满足以下所有条件： 1. 修复命令已完成 2. 修复增量通过了对抗性验证 3. 每个声明的验证命令都以退出代码 0 退出 4. 存在必需的回归测试证据 基于抑制或不完整的修复将变为 `REPAIR_REJECTED`。它永远不会计入就绪门禁。 ## Repository 导航 ``` src/ approvals/ append-only approval decisions catalog/ embedded inert catalog contracts/ embedded JSON Schema validation distribution/ package archive and distribution checks engine/ ordered runtime and capability execution evidence/ command and repair artifacts findings/ normalization and persistence inspect/ project inspection platform/ agent detection, guarantees, and degradations playbook/ immutable playbook loading report/ HARDENING.md rendering runtime/ embedded package metadata state/ atomic state and event journal validation/ repair snapshots and adversarial checks schemas/ manifest, playbook, state, finding, and lock schemas playbooks/ inert examples and reference playbooks skills/ canonical agent-neutral Dokion workflow scripts/ validation, smoke-test, guard, and release tools templates/ report and implementation contracts tests/ seeded-defect and runtime acceptance tests ``` ## 完成声明措辞 Dokion 绝不会做出未经限定的、声称某个 repository 已达到生产环境就绪状态的断言。 有效的完成声明其范围仅限于：用户配置的门禁、已测试的提交、已存储的证据、平台降级以及记录在 `HARDENING.md` 中的限制。 ## 许可证 MIT。参见 [LICENSE](LICENSE)。

标签：AI编程助手, Bun, SOC Prime, 工作流引擎, 开发工具, 自动化攻击, 逆向工具