DevTime

DevTime

DevTime 验证你的代码库实际上能证明什么。

名为 stripe/webhook.ts 的文件看起来像是代码库处理 Stripe webhook 的证明。但它可能只是一个只返回 404 的处理程序。DevTime 会根据代码库的实现、测试、配置和记录的决策来核查相关陈述，然后报告哪些内容得到支持、哪些与事实矛盾、哪些内容缺失，以及哪些内容已经过时。

无云端服务。无遥测。无代码执行。无需 AI。

更喜欢看视频？观看 2 分钟演示：DevTime 在本地扫描代码库，根据证据解释概念，指出不确定之处，发现有风险的差异，并展示一项得到佐证的决策如何帮助加深理解。

---

60 秒体验 DevTime

pipx install devtime-ei
dtc demo init
cd devtime-demo-saas
dtc init
dtc scan
dtc verify

在演示代码库中，账单 webhook 签名验证和 JWT 身份验证的结果为 SUPPORTED，路由测试关联的结果为 WEAK，因为这些路由没有任何测试导入。将它指向你自己的代码库，答案就会改变：

cd your-repo
dtc init && dtc scan && dtc verify

PyPI 发行包名为 devtime-ei。Python 包仍名为 devtime，CLI 命令仍为 dtc。dtc demo init 会将一个小型静态示例代码库复制到 ./devtime-demo-saas，让你无需克隆此代码库即可试用 DevTime。

从源代码运行

git clone https://github.com/Shakargy/devtime.git
cd devtime
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
cd examples/demo-saas
dtc init
dtc scan
dtc concepts
dtc explain "Billing Webhooks"

在 Windows PowerShell 中：

git clone https://github.com/Shakargy/devtime.git
cd devtime
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e ".[dev]"
cd examples/demo-saas
dtc init
dtc scan
dtc concepts
dtc explain "Billing Webhooks"

你应该会看到根据证据解释的 Billing Webhooks，包括受支持的声明、文件引用、不确定之处、Understanding Score 和 Understanding Debt。

要测试风险审查，请先进行本地修改，然后运行：

dtc risk --diff

完整且可直接复制粘贴的操作指南（包括风险差异和佐证决策步骤）见 DEMO_SCRIPT.md。

验证声明（实验性）

声明是关于代码库的陈述。验证会给出状态和凭据作为回答，绝不会声称证据无法支持的确定性。

Status: CONTRADICTED

Contradictions:
  - The billing webhook endpoint cannot verify signatures
    because it is a disabled stub.
      claimed:  pages/api/stripe/webhook.ts is named and routed
                as a billing webhook endpoint.
      observed: The handler's only behavior is a 404/501 response.

• SUPPORTED - 当前扫描中存在所需的行为证据
• WEAK - 存在相关表面，但缺少证明证据
• CONTRADICTED - 可信证据与声明相冲突，并展示双方证据
• UNKNOWN - 存在相关表面，但无法负责任地判断覆盖情况
• NOT_APPLICABLE - 代码库中不存在与此声明相关的表面

内置四项声明：路由测试关联、管理员授权、账单 webhook 签名和 JWT 身份验证。dtc verify 会优先展示它在你的代码库中实际能够验证的内容；如果没有任何适用项，它会说明需要什么才能验证某项声明，而不会让你陷入僵局。

真实性与时效性是分开的：已验证声明所依据的文件发生变化时，该声明会变为 STALE，并指出相应文件。

要审查更改，请比较两个提交中的声明：

dtc review --base origin/main

它会根据两个提交的独立快照报告更改对各项声明的影响（回归、新近适用的声明，或原本成立的声明下发生变化的证据），且不会触碰你的工作树。它也会在 GitHub Actions 中以建议性作业摘要的形式运行。

完整模型及其局限性请参阅 VERIFICATION.md。

为什么要做这个项目

Git 会记录发生了什么变化，却不会保留这些变化背后的推理。当你再次查看某个代码库，或审查一个并非由你编写的代码库时，往往需要重新梳理某项行为为何存在、有哪些证据支持它，以及哪些内容仍不确定。

DevTime 会构建有证据支撑的代码库记忆：一个本地层，帮助代码库根据代码、测试、配置、路由和记录的决策来解释自身。它会展示代码库有证据支持什么，以及同样重要的——它目前还无法支持什么。

适用人群

DevTime 适合需要依据证据而非记忆来了解代码仓库的人。

如果你：

• 正在熟悉不熟悉的代码库，需要了解某项功能是如何实现的；
• 正在审查拉取请求，想查看有哪些证据支持某项行为；
• 几周或几个月后重新回到一个项目，已经不记得某些内容为何存在；
• 维护一个长期运行的项目，其中的设计决策很容易被遗忘；
• 希望对代码仓库的理解有代码和记录下来的决策作为依据，而不是依赖自动生成的摘要；

那么 DevTime 会特别有用。

DevTime 可以帮助回答以下问题：

• 这个代码仓库能否真正证明其文件名所暗示的内容？
• 身份验证实际上是在哪里实现的？
• 哪些文件可以证明 Billing Webhooks 的存在？
• 还有哪些内容尚不确定？
• 这个差异是否触及了有风险的概念？
• 是否有解释这种行为的决策记录？

DevTime 的功能

• 验证对代码仓库的主张，并报告状态、证据以及任何矛盾双方的情况。
• 跟踪时效性，因此证据发生变化时，已验证的主张会变为过时。
• 从路由、测试、配置、依赖项和文档中检测概念。
• 通过将主张关联到文件和信号，基于证据进行说明。
• 在证据缺失或薄弱时指出不确定性。
• 使用理解度评分和理解债务标签评估理解程度。
• 对范围较窄且有风险的差异进行审查，并提供建议性发现，包括差异会动摇哪些已验证的主张。
• 在本地记录决策，以便有代码佐证时，决策依据可以降低不确定性。

支持的概念

验证功能的底层是一个扫描器，它会构建本地且有证据支持的记忆：

DevTime 可检测六类受支持的概念。目前还无法发现任意领域概念：

• 身份验证
• Billing Webhooks
• 后台任务
• 数据导出
• 管理员权限
• 文件上传

目前，除此六类之外的所有内容均不在支持范围内。请参阅 LIMITATIONS.md。

DevTime 不会做什么

• 它不会执行你的代码。
• 它不会通过网络发送代码或数据。
• 它不需要也不会调用 AI 模型。
• 它不保证正确性或修改安全性。
• 它不能取代代码审查或架构决策。
• 它不是文档生成器、静态分析器、可观测性工具、生产力跟踪器或 AI 编码 Agent。

信任模型

• DevTime 会将本地代码仓库记忆存储在 .devtime/ 中（本地 SQLite 数据库）。
• 扫描期间不访问网络。
• 扫描期间不执行代码。
• 在扫描前会先裁剪被忽略的目录；被忽略的文件和机密信息绝不能成为证据或主张。
• 每项主张都必须关联到证据——没有证据，就没有主张。
• 证据薄弱时，应产生不确定性，而非信心。
• 使用不等于决策：使用了某个依赖项，并不意味着有人决定了使用它的原因。
• 默认情况下，风险审查仅提供建议——不会阻止 PR。

命令

命令	用途
dtc init	创建本地 .devtime 记忆。
dtc scan	扫描当前仓库，并提取有证据支持的信号。
dtc concepts	列出检测到的概念及其置信度和理解债务。
dtc explain <concept>	解释一个概念：主张、证据、置信度、不确定性和理解债务。
dtc context <concept>	为 Agent 或人类创建受治理的上下文包。
dtc risk --diff	使用本地证据审查 git diff 中的高风险更改（仅供参考）。
dtc decision add	添加本地决策记录，以减少不确定性。
dtc verify [claim]	根据证据验证仓库中的主张：状态、矛盾和时效性（实验性）。
dtc review --base <ref>	比较两个提交中的主张，并报告更改对它们的影响（仅供参考）。

（另有：dtc evidence、dtc debt、dtc status、dtc doctor --privacy、 dtc export、dtc reset、dtc mcp start。）

需要 Python >= 3.11 和 git。请参阅 QUICKSTART.md，了解 分步首次运行指南和故障排除。

与编码 Agent 配合使用（MCP）

编码 Agent 每次开始会话时，对你的仓库都一无所知，然后还会自信地猜测。 DevTime 为它提供值得信赖的记忆：一个本地只读 MCP 服务，只会根据仓库能够证明的主张作答， 并明确指出无法确定的内容。

安装支持 MCP 的版本并扫描你的仓库：

pipx install "devtime-ei[mcp]"
cd your-repo
dtc init
dtc scan

将 DevTime 添加到 Claude Code：

claude mcp add devtime -- dtc mcp start

或者在任何可读取 .mcp.json 的 MCP 客户端中使用：

{
  "mcpServers": {
    "devtime": {
      "command": "dtc",
      "args": ["mcp", "start"]
    }
  }
}

Agent 可使用四种只读工具：list_concepts、explain_concept、 get_context_pack（受治理的上下文，包含未经审查不得更改的路径、要运行的测试 和 Agent 指南），以及 verify_claim（主张状态、矛盾和缺失证据；每次实时计算，绝不持久化）。仅限本地 stdio——没有网络侦听器，没有写入工具，不会返回源代码，只提供证据文件路径。

DevTime 已在官方 MCP Registry 中列出，名称为 io.github.Shakargy/devtime。

安装

推荐：通过 pipx 从 PyPI 安装，这样 dtc 命令就能在隔离环境中通过 PATH 使用：

pipx install devtime-ei

也可通过 pip 安装：

pip install devtime-ei

PyPI 发行包名为 devtime-ei。Python 包仍名为 devtime，CLI 命令仍为 dtc。安装后，运行 dtc demo init，即可创建一个本地示例仓库进行试用。

从源代码安装

git clone https://github.com/Shakargy/devtime.git
cd devtime
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"

Windows PowerShell：

git clone https://github.com/Shakargy/devtime.git
cd devtime
python -m venv .venv
.venv\Scripts\Activate.ps1
pip install -e ".[dev]"

输出示例

$ dtc explain "Billing Webhooks"
Concept: Billing Webhooks

Supported claims:
  - Billing Webhooks is present and supported by behavior evidence.
    type: concept  confidence: 0.86  evidence: src/billing/stripe-webhook.ts, tests/stripe-signature.test.ts
  - Billing Webhooks has active route handling.
    type: behavior  confidence: 0.82  evidence: src/billing/stripe-webhook.ts
  - Billing Webhooks verifies webhook signatures.
    type: behavior  confidence: 0.85  evidence: src/billing/stripe-webhook.ts

Uncertainty:
  - No decision was found explaining key choices for Billing Webhooks.

Understanding Score: 58 / 100
Understanding Debt: medium
causes:
  - missing or uncorroborated decision evidence
  - no confirmed owner

理解分数越高，表示理解程度越好；理解债务是一个标签（低/中/高），并非同一个数值。

验证

DevTime 可在 examples/demo-saas 和真实仓库上运行。在 Reality Validation 期间，它检测到真实故障并从中学习——包括对 Next.js App Router 的盲区、 在通用 Webhook 系统上误判为 Billing Webhooks、将数据库迁移错误计为 Background Jobs 证据等。每个故障都被加入测试样例，防止其悄无声息地再次出现。

• 随着真实故障被加入测试样例，测试数量从 13 增至 88。
• 在一个包含 355 个文件的真实仓库中，通过剪除被忽略的目录，扫描时间从约 27.3 秒降至约 0.48 秒。

完整证据、前后示例和验证报告见 PROOF.md 和 reports/reality-validation/。

隐私与安全

• 完全在本地运行；扫描期间不会有任何内容离开你的计算机。
• 扫描期间不会执行代码，也不会发起网络调用。
• 按设计，机密信息和被忽略的文件不会纳入证据（dtc doctor --privacy 会报告这些边界）。
• dtc reset 会删除本地记忆；绝不会修改你的源代码。

已知限制

DevTime 是一个启发式扫描器，不是完整的编译器或语义分析器。目前，它在与其测试样例相似的 TypeScript / Next.js / Express / FastAPI 风格代码仓库中表现最佳。可能出现误报和漏报。理解债务是一种产品信号，并非客观且普遍适用的真理。

请在 LIMITATIONS.md 中阅读完整列表，包括框架覆盖范围、风险审查范围，以及有意暂未构建的内容。

路线图

这是一个早期的本地优先 V0，重点是在扩大规模之前建立信任。尚未构建（有意为之）的内容：Git 历史信号、可写入的 MCP 工具、AI 提供商、UI，以及任何云端、团队或企业功能。请参阅 ROADMAP.md。

参与贡献

最有价值的贡献是一个测试样例：一个小型代码仓库模式，以及预期概念、允许的声明、禁止的声明和必须体现的不确定性。如果 DevTime 在你的代码上出错，这个错误输出可以成为测试样例，从而避免回归。请参阅 CONTRIBUTING.md。

许可证

基于 Apache License 2.0 许可。请参阅 LICENSE。