sydneyvb-nl/tellur

# Tellur **为交付 AI 辅助软件的团队提供的本地优先的 AI 代码溯源方案。** [](https://tellur.dev) [](LICENSE) [](Cargo.toml) [](docs/ADAPTERS.md) Git 告诉你改变了**什么**。Tellur 告诉你 **AI 是如何参与的**。 Tellur 会在你的仓库中记录 AI 辅助开发的证据：哪个 agent 修改了哪些行、使用了什么 model 和 prompt 哈希、是否运行了测试，以及敏感的更改是否需要人工审查。它是开源的、本地优先的，专为需要 AI 生成代码审计追踪的开发者、维护者、安全审查人员和团队而构建。 **网站：** [tellur.dev](https://tellur.dev) ## 为什么开发者会 Star Tellur - **AI 代码归属：** 说明某一行代码是人类编写的、AI 生成的，还是混合编写的。 - **本地优先溯源：** 将证据存储在 `.tellur/` 中；源代码不需要离开你的机器。 - **防篡改审计追踪：** 仅追加的 JSONL 事件通过 SHA-256 哈希链进行密封。 - **PR 风险报告：** 在合并之前，展示 AI 参与情况、敏感路径、测试证据和审查缺口。 - **多 agent 适配器：** 捕获或导入来自 Codex、Claude Code、Cursor、VS Code/Copilot、Gemini CLI、Antigravity、Aider 和通用工具的证据。 - **策略即代码：** 为 auth、payments、secrets、infra、被阻止的 AI 读取、必需的测试和必需的人工审查定义规则。 ## 问题所在 AI 编码 agent 现已成为日常软件开发的一部分，但大多数团队在审查 AI 辅助的更改时，依然仅使用标准的 Git 元数据。这导致一些重要的问题无法解答： - 哪些代码行是 AI 生成的、人类编写的，还是混合编写的？ - 哪次更改是由哪个 model、工具、prompt 哈希和会话产生的？ - agent 是否触碰了安全敏感代码，例如 auth、payments、secrets 或基础设施？ - 在更改合并之前运行测试了吗？ - 由于 AI 的参与，某个 PR 是否需要额外的审查？ Tellur 将这些问题转化为本地、可查询的证据，用于代码审查、合规性、供应链溯源和工程治理。 ## Tellur 的作用 | 功能 | 你能得到什么 | | --- | --- | | 行级归属 | 代码范围映射到 agent、model、会话、prompt 哈希、证据强度和置信度得分。 | | 会话捕获 | 来自 CLI 命令、编辑器钩子、导入器、MCP 和本地 daemon 的 AI 辅助活动。 | | PR 风险报告 | AI 参与情况、敏感路径、测试证据、审查缺口和策略警告。 | | 防篡改日志 | 仅追加的 JSONL 带有用于本地验证的 SHA-256 哈希链。 | | 快速本地查询 | SQLite 索引为 CLI、VS Code/Cursor 扩展、MCP 工具、daemon 和 dashboard 视图提供支持。 | | 可移植导出 | 面向开发者、OSS、企业、审计、发布和 CI 工作流的溯源包。 | | 敏感信息脱敏 | 清理常见的密钥、token、密码和私钥材料。 | ## 状态 Tellur 目前处于测试阶段。本地 pipeline 已实现端到端功能： ``` capture -> attribution -> event log -> SQLite index -> CLI/editor/reports ``` 已实现的界面包括 CLI、全局 Codex/Claude Code/Gemini CLI/Antigravity 钩子、Cursor MCP/设置、VS Code/Cursor 扩展捕获，以及针对 Cursor、Aider、Codex CLI、Gemini CLI、Antigravity、GitHub Copilot、Windsurf/Cascade、JetBrains AI/Junie、Devin、Continue 和 Cline/Roo Code 的导入器，一个本地 token 认证的 daemon，一个 MCP stdio 服务器，溯源导出和 Git notes 互操作。对于团队，自托管的 `tellur-server` 中心增加了多租户的摄取/读取/报告/策略/导出功能，并支持 OIDC SSO、SCIM 配置、持久化任务和嵌入式 Web dashboard（概览、仓库、会话、策略合规性、人员与访问权限、审计日志和导出）。 ## 安装 从源码安装： ``` cargo install --path crates/cli ``` 用于开发： ``` cargo build cargo test cargo run -p tellur-cli -- --help ``` Tellur 目前以 Rust stable 和 2024 edition 为目标。 ## 快速开始 在 Git 仓库中初始化 Tellur： ``` tellur init ``` `tellur init --profile` 接受 `default`、`team` 和 `oss-maintainer`。不受支持的配置文件名称会快速失败，而不是静默使用默认设置。 检查本地设置和检测到的 AI 工具： ``` tellur doctor ``` 开始捕获文件更改： ``` tellur watch ``` 安装一次性全局 agent/编辑器集成： ``` tellur setup agents ``` 一旦你运行了 `tellur setup agents`（参见[一次性 Agent 设置](#one-time-agent-setup)），大多数 agent 都会被**实时**捕获。使用 `tellur import` 来回填历史记录，或用于仅公开导出功能的工具： ``` tellur import claude-code path/to/transcript.jsonl tellur import codex path/to/codex-events.jsonl tellur import gemini-cli path/to/gemini-events.jsonl tellur import cursor path/to/agent-trace.json tellur import copilot path/to/copilot-metadata.jsonl tellur import aider path/to/repo # an Aider git repository tellur import windsurf path/to/cascade-session.jsonl tellur import jetbrains path/to/ai-assistant-export.json tellur import devin path/to/devin-run.json tellur import continue path/to/.continue/dev_data/chat.jsonl tellur import cline path/to/tasks//ui_messages.json ``` 还可选择：`antigravity` 和 `generic` (JSONL)。有关完整列表，请参见 `tellur import --help`。 查询归属： ``` tellur explain src/auth/session.ts:84 tellur blame src/auth/session.ts ``` 生成 PR 报告： ``` tellur pr-report --base main --head HEAD ``` 验证事件日志： ``` tellur verify ``` ## CLI 参考 ``` tellur init # Initialize .tellur/ tellur doctor # Check setup and detect tools tellur status # Show repository capture status tellur watch # Capture working tree changes tellur explain # Explain attribution for one line tellur blame # Show file attribution ranges tellur sessions # List captured sessions tellur pr-report --base main # Generate a PR risk report tellur policy check # Evaluate configured policies tellur event --event-type file.write --session --file tellur import # Import external AI tool data tellur login --hub # Sign in to a team hub (browser; no token to paste) tellur push # Send captured events + AI attribution to the hub tellur logout # Forget stored hub credentials tellur export --format json # Export provenance data tellur notes export # Write Git AI-compatible refs/notes/ai tellur notes import # Import refs/notes/ai into the local index tellur notes push # Push refs/notes/ai to origin tellur notes fetch # Fetch refs/notes/ai from origin tellur team report # Aggregate AI involvement across a commit range (no server) tellur daemon # Run local HTTP ingestion/dashboard API tellur mcp # Run MCP server over stdio tellur setup agents # Install one-time global agent/editor integrations tellur setup cursor # Install Cursor MCP/settings integration tellur setup vscode # Install VS Code extension settings tellur setup windsurf # Install Windsurf MCP/settings integration tellur setup gemini-cli # Install Gemini CLI hooks tellur setup antigravity # Install Antigravity hooks/MCP integration tellur setup status # Check global agent integration status tellur gc --dry-run # Garbage-collect expired events tellur redact # Redact secrets from stored events tellur verify # Verify hash-chain integrity ``` `explain`、`blame` 和 `sessions` 支持 `--json` 以输出机器可读的内容。 ## 支持的适配器和集成 | 工具 | 机制 | 状态 | | --- | --- | --- | | Claude Code | 用户/项目生命周期钩子 + 会话记录导入 | 可用 | | Codex CLI/App | 用户生命周期钩子、本地个人插件、JSONL 导入 | 可用 | | Gemini CLI | 用户生命周期钩子、JSONL 导入 | 可用 | | Google Antigravity 2.0 | 用户钩子、MCP 配置、JSONL 导入 | 可用 | | Cursor IDE/CLI | Cursor MCP/设置、VS Code 兼容的扩展保存/监视捕获、JSON/JSONL 导入 | 可用 | | VS Code/Copilot | VS Code 扩展自动初始化、监视、保存捕获、显式 prompt 哈希处理、元数据导入 | 可用（受限于 VS Code API） | | Aider | Git 提交归属导入 | 可用 | | GitHub Copilot | 元数据 JSON/JSONL 导入 | 可用 | | Windsurf / Cascade | Windsurf MCP/设置、VS Code 兼容的扩展保存/监视捕获、Cascade 会话 JSON/JSONL 导入 | 可用 | | JetBrains AI Assistant / Junie | JetBrains 插件保存/监视捕获 (`editor/tellur-jetbrains`) + 操作日志 JSON/JSONL 导入 | 可用 | | Devin | 通过 daemon webhook 实时捕获 (`POST /webhook/devin`) + 云端 agent 运行/会话导出导入 | 可用 | | Continue | `dev_data` JSONL 导入；在 VS Code 系列编辑器中运行时进行实时保存/监视捕获 | 可用 | | Cline / Roo Code | 任务历史 JSON/JSONL 导入；在 VS Code 系列编辑器中运行时进行实时保存/监视捕获 | 可用 | | Generic | CLI 事件、JSONL、本地 HTTP daemon | 可用 | 导入适配器会保留源事件 ID、源时间戳、会话 ID、参与者、事件类型和 payload，同时重新计算 Tellur 的本地哈希链。无效的非空 JSON/JSONL 行会导致导入失败，而不是被静默跳过。类 prompt 字段存储为哈希，而不是原始 prompt 文本；保留元数据中类似敏感信息的字符串会被脱敏。 `tellur import aider ` 期望 `` 是一个 Git 仓库路径。除非特定于适配器的文档另有说明，其他导入适配器均期望一个文件路径。 适配器层是可插拔的，因此其他工具可以将它们的事件规范化为 Tellur 的 schema，而无需更改核心归属引擎。 有关当前的适配器保证、已知限制和采用路线图，请参见 [`docs/ADAPTERS.md`](docs/ADAPTERS.md)。 ### 导入之外的实时捕获 有些工具没有记录在案的本地生命周期钩子，因此 Tellur 通过它们各自公开的持久表面来捕获： - **JetBrains IDE (AI Assistant / Junie)** — [`editor/tellur-jetbrains`](editor/tellur-jetbrains) 插件订阅 IDE 的虚拟文件更改，并将保存/创建的文件报告给 `tellur hooks ingest --source jetbrains --auto-init`。由 JetBrains AI Assistant 和 Junie agent 所做的编辑通过相同的路径落盘，因此它们可以被实时捕获。JetBrains MCP 是在 IDE 中配置的，因此 Tellur 不会自动写入它。当捕获任务正在排队或运行时，该插件会对同一文件/仓库的重复 VFS 事件进行去重；如果在活动捕获期间有新的保存操作到达，它会再重新运行一次捕获；它通过一个一次性的有界单工作线程队列发送捕获任务，并记录 CLI 故障/超时以供故障排除。 - **Devin (云端 agent)** — 没有本地文件表面。将 Devin webhook（或一个中继）指向本地 daemon 的已认证 `POST /webhook/devin` 端点，该端点会将 Devin 的原生运行/会话 payload（消息、shell 命令、文件编辑、状态）规范化为 Tellur 事件并重新计算哈希链。该端点是通用的：对于任何其 webhook 发送类似结构数据的工具，`POST /webhook/{source}` 均可起作用。 daemon webhook 需要与其他更改状态端点相同的 bearer token（参见 `.tellur/daemon.token`），并且仅接受 loopback 主机： ``` curl -X POST http://127.0.0.1:4917/webhook/devin \ -H "Authorization: Bearer $(cat .tellur/daemon.token)" \ -H 'Content-Type: application/json' \ -d '{"devin_run_id":"run-1","messages":[{"type":"edit","file_path":"src/app.py"}]}' ``` ## 一次性 Agent 设置 对于 Codex、Claude Code、Gemini CLI、Antigravity、Cursor、VS Code 和 Windsurf，Tellur 支持用户级安装，因此用户不需要在每个项目中调用 skill 或插件： ``` tellur setup agents ``` 这会为 Claude Code (`~/.claude/settings.json`) 和 Codex (`~/.codex/hooks.json`) 安装全局钩子。它会在 `~/.codex/plugins/tellur-provenance` 下发布一个本地 Codex 个人插件，并在 `~/.agents/plugins/marketplace.json` 中添加一个 marketplace 条目，用于手动执行诸如状态检查、验证和 PR 报告等工作流。它会将 Gemini CLI 钩子写入 `~/.gemini/settings.json`，Antigravity 钩子写入 `~/.gemini/config/hooks.json`，Antigravity MCP 配置写入 `~/.gemini/antigravity/mcp_config.json` 和 `~/.gemini/antigravity-cli/mcp_config.json`，Cursor MCP/设置（`~/.cursor/mcp.json` 加上 Cursor 用户设置），VS Code 用户设置，以及 Windsurf MCP/设置（`~/.codeium/windsurf/mcp_config.json` 加上 Windsurf 用户设置），以便 Tellur 扩展能够在每个 Git 工作区中自动初始化、监视和捕获已保存的文件。 全局钩子会调用已安装的 `tellur` 可执行文件的绝对路径： ``` /absolute/path/to/tellur hooks ingest --source --auto-init ``` 当钩子在 Git 仓库之外运行时，它将不执行任何操作。当它在没有 `.tellur/` 的 Git 仓库中运行时，`--auto-init` 会使用安全的默认值创建本地 Tellur 存储。要禁用对某个仓库的捕获，请创建 `.tellur/disable`。无效的钩子 payload 不执行任何操作，并且仅当钩子 payload 包含具体的文件路径时，工具钩子才会捕获工作树的更改。 使用 `tellur setup status` 检查已安装的全局集成，并使用 `tellur setup uninstall` 删除由 Tellur 安装的全局钩子以及本地 Codex 插件、Cursor MCP/设置、VS Code 设置和 Windsurf MCP/设置。 Cursor、VS Code 和 Windsurf 没有与 Codex 相同的文档化的本地生命周期钩子模型。因此，Tellur 使用它们公开的持久编辑器表面：扩展保存/监视捕获、MCP 工具、显式 prompt 哈希处理、Git 策略检查和导入适配器。因为 Windsurf 是一个 VS Code 兼容的编辑器，所以相同的 Tellur 扩展捕获也会记录在其中运行的 agent 所做的编辑，包括 Cline / Roo Code 和 Continue。 ### 集成机制 | 表面 | 设置命令 | 写入的文件 | 运行时行为 | | --- | --- | --- | --- | | Claude Code | `tellur setup claude-code` 或 `tellur setup agents` | `~/.claude/settings.json` | 生命周期钩子调用 `tellur hooks ingest --source claude-code --auto-init`；项目钩仍可通过 `tellur hooks install claude-code` 使用。 | | Codex CLI/App | `tellur setup codex` 或 `tellur setup agents` | `~/.codex/hooks.json`, `~/.codex/plugins/tellur-provenance`, `~/.agents/plugins/marketplace.json` | 用户钩子调用 `tellur hooks ingest --source codex --auto-init`；本地插件通过 Codex 的插件目录暴露手动的 Tellur 工作流。 | | Gemini CLI | `tellur setup gemini-cli` 或 `tellur setup agents` | `~/.gemini/settings.json` | Gemini 的 `BeforeTool`/`AfterTool`/agent/session 钩子调用 `tellur hooks ingest --source gemini-cli --auto-init --json-response`。 | | Antigravity 2.0 | `tellur setup antigravity` 或 `tellur setup agents` | `~/.gemini/config/hooks.json`, `~/.gemini/antigravity/mcp_config.json`, `~/.gemini/antigravity-cli/mcp_config.json` | Antigravity 生命周期钩子调用 `tellur hooks ingest --source antigravity --auto-init --json-response`；MCP 将 Tellur 工具暴露给 Antigravity agent。 | | Cursor | `tellur setup cursor` 或 `tellur setup agents` | `~/.cursor/mcp.json`, Cursor 用户 `settings.json` | Cursor 可以调用 Tellur MCP 工具；已安装的 Tellur 扩展使用源为 `cursor` 的自动初始化、监视和保存捕获。 | | VS Code | `tellur setup vscode` 或 `tellur setup agents` | VS Code 用户 `settings.json` | 已安装的扩展会自动初始化 Git 工作区，启动 `tellur watch`，并通过安全的钩子摄取捕获已保存的文件（源为 `vscode`）。 | | Windsurf / Cascade | `tellur setup windsurf` 或 `tellur setup agents` | `~/.codeium/windsurf/mcp_config.json`, Windsurf 用户 `settings.json` | Windsurf 可以调用 Tellur MCP 工具；已安装的 VS Code 兼容扩展使用源为 `windsurf` 的自动初始化、监视和保存捕获。 | 所有设置命令都会写入绝对的 `tellur` 可执行文件路径。现有的格式错误的 JSON 设置不会被覆盖；设置将会失败，以便用户修复或备份该文件。 ## 数据模型 Tellur 将仓库本地数据存储在 `.tellur/` 下： ``` .tellur/ ├── config.yml # Configuration, intended to be committed ├── policies/ │ └── default.yml # Policy rules, intended to be committed ├── traces/ │ └── sessions/ # JSONL event logs, gitignored by default ├── index/ │ └── tellur.db # SQLite index, gitignored by default └── exports/ # Generated provenance bundles ``` 带有版本的 JSON schema 位于 [`schemas/`](./schemas/)： | Schema | 描述 | | --- | --- | | `tellur.session.v1` | 有边界的 AI 辅助开发交互 | | `tellur.event.v1` | 会话中带有时间戳的操作 | | `tellur.attribution.v1` | 文件的行级源映射 | | `tellur.pr-report.v1` | 包含 AI 参与统计的 PR 风险报告 | | `tellur.provenance.v1` | 可移植的导出包 | ## 策略示例 ``` # .tellur/policies/default.yml version: 1 sensitive_paths: - path: "src/auth/**" tags: ["auth", "security-sensitive"] require_human_review: true require_tests: true - path: "**/.env*" tags: ["secrets"] block_ai_read: true rules: - id: require-tests-for-ai-code description: "AI code changes > 20 lines require test evidence" when: attribution.origin: ai changed_lines.greater_than: 20 action: warn require: tests_run: true ``` ## 架构 ``` Tellur/ ├── crates/ │ ├── core/ # Schemas, attribution, storage, policy, export, daemon, MCP │ ├── cli/ # tellur command │ ├── adapters/ # Claude Code, Cursor, Aider, Codex, Copilot, Gemini, Antigravity, Windsurf, JetBrains, Devin, Continue, Cline, Generic │ └── server/ # Tier 1 team hub (tellur-server) — FSL-1.1-ALv2 (in progress) ├── editor/ # VS Code extension + JetBrains plugin (tellur-jetbrains) ├── schemas/ # JSON Schema definitions ├── dist/ # npm wrapper and Homebrew formula └── web/ # Session replay dashboard ``` 核心存储被刻意保持简单：仅追加的 JSONL 用于可审计性，SQLite 用于查询速度，Git blob SHA 用于在不同文件状态间实现稳定的归属追踪。 ## Git Notes 互操作 Tellur 可以使用 Git AI 兼容的 `refs/notes/ai` 命名空间，将紧凑的作者证明发布为 Git notes： ``` tellur notes export --print # inspect the note payload tellur notes export # attach it to HEAD tellur notes push # publish refs/notes/ai tellur notes fetch # fetch refs/notes/ai tellur notes import # import a note back into Tellur's local index ``` Git notes 被视为一种互操作性和传输层，而不是 Tellur 的主数据库。Prompt、会话记录、脱敏状态、重放数据和策略证据保留在 Tellur 的本地/私有存储中；notes 仅包含行范围、轻量级会话元数据和提交范围的归属。 ## 团队报告（无需服务器） 由于作者 notes 通过现有的 Git 远程仓库传输，整个团队无需运行任何服务器即可共享 AI 溯源。在贡献者推送他们的 `refs/notes/ai` 后，任何人都可以将 PR 或分支范围聚合到一个视图中： ``` tellur notes fetch # get teammates' notes from origin tellur team report --base main --head HEAD # Markdown summary tellur team report --base main --head HEAD --json ``` 报告会显示 AI 辅助行与人工行、按工具/model/作者的细分，以及溯源覆盖率（范围内哪些提交带有 note）。它是容错的：没有 note 或 note 无法解析的提交会被列在“无溯源”下，而不会导致报告失败。这是团队/服务器路线图中的无服务器（“Tier 0”）部分；请参见 [`docs/proposals/TEAM_SERVER_MODE.md`](docs/proposals/TEAM_SERVER_MODE.md)。 要自动在 pull request 上发布报告，请将 [`docs/examples/github-actions-team-report.yml`](docs/examples/github-actions-team-report.yml) 中的示例工作流复制到 `.github/workflows/` 中。 ## 自托管团队中心（预览版） 对于需要共享、基于服务器的视图的团队，Tellur 提供了一个可选的自托管中心 `tellur-server`（位于 `crates/server` 中）。它是**在 FSL-1.1-ALv2 下源代码可见**（Apache-2.0 核心/CLI/适配器不受影响），并且正在积极开发中——请参见 [`docs/proposals/TEAM_SERVER_MODE.md`](docs/proposals/TEAM_SERVER_MODE.md) 和 [`docs/proposals/TEAM_SERVER_IMPLEMENTATION.md`](docs/proposals/TEAM_SERVER_IMPLEMENTATION.md)。 本地优先仍然是默认设置：该中心是可选的，除非你明确允许，否则它被绑定在 loopback 上，通过 token 认证，并进行租户隔离。 ### 运行它 ``` tellur-server admin create-org --name "Acme" tellur-server admin create-token --org --role admin # printed once tellur-server admin set-policy --org --file policy.yml # optional tellur-server # serve at 127.0.0.1:4920 ``` 或者在容器中运行整个程序（包括内置的 dashboard）： ``` docker compose -f dist/docker/docker-compose.yml up --build ``` CLI 客户端可以将中央策略拉取到仓库中： ``` tellur policy pull --org --hub http://hub:4920 --token ``` ### API 所有 `/v1` 路由都是组织范围内的，并通过 Bearer token（或者在浏览器中通过 SSO 会话 cookie）进行身份验证。跨组织访问将被拒绝并记录在案。 - **摄取** — `POST /v1/orgs/{org}/repos/{repo}/events`（敏感信息脱敏 + 重新验证每个仓库的哈希链）和 `POST .../attributions`。 - **读取** — `GET .../repos`, `.../events`, `.../report`, `.../overview`, `.../sessions[/{id}]`, `.../audit`。 - **策略** — `PUT/GET .../policies[/{name}]`; `POST/GET .../policies/compliance`（持久化评估 + 快照）。 - **导出** — `POST .../export/events|audit|evidence` 将持久化任务加入队列（通过 `GET .../jobs[/{id}]` 进行轮询）；基于仓库的 `GET/POST .../export/slsa|spdx` 生成 SLSA v1.0 / SPDX SBOM 证明。 - **设备登录** — `POST /v1/device/authorize` + `/v1/device/token` 支持 CLI 的 `tellur login` (RFC 8628 设备授权)；人类需要在 `/auth/device` 处进行批准。 - **运维** — `GET /healthz`, `/readyz`, `/metrics` (Prometheus)；无需认证，无租户数据。 ### 存储与保留 默认后端是嵌入式 **SQLite**（零配置，单节点）。为了实现水平扩展，请将 `TELLUR_DATABASE_URL` 设置为 **Postgres** DSN；Postgres 通过 NoTls 访问，因此请将其保持在私有网络中或放在 TLS 终止代理后面。后台保留循环会最大程度地减少静态数据：过期的会话和过时的登录事务总是会被修剪，已完成任务在 `TELLUR_RETENTION_DAYS` 后修剪，审计条目在 `TELLUR_AUDIT_RETENTION_DAYS` 后通过**密封检查点**修剪（旧条目会被删除，但已修剪前缀的尖端哈希会被保留，因此链条仍然可以验证）。这两个窗口默认都为 `0` = 永久保留；事件溯源日志永远不会被修剪。 ### 认证与授权 - **RBAC** — `viewer` / `contributor` / `admin`，外加**基于仓库的附加授权**（`PUT/DELETE .../repos/{repo}/roles/{member}` 或 `tellur-server admin grant-repo-role`）。有效角色是 `max(组织角色, 授权)`；授权只能提升权限，不能限制权限。 - **SSO (OIDC)** — 授权码 + PKCE。设置 `TELLUR_OIDC_ISSUER`、`TELLUR_OIDC_CLIENT_ID`、`TELLUR_OIDC_CLIENT_SECRET`、`TELLUR_OIDC_REDIRECT_URI` 以启用 `/auth/login|callback|logout`。登录会颁发一个不透明的、存储在服务器上的会话 cookie（`HttpOnly` / `Secure` / `SameSite=Lax`）。没有开放的自注册：使用 `tellur-server admin add-member` 预先配置成员，在首次登录时通过已验证的电子邮件进行匹配，并绑定到他们的 OIDC 主体。签发者/端点必须是 **`https`**（ID-token 完整性依赖于 TLS）；`http` 仅允许用于 loopback，或者——对于受信任的私有网络/家庭实验室——需要明确的、**不安全**的许可 `TELLUR_OIDC_ALLOW_INSECURE_HTTP=1`（例如局域网内位于 `http://192.168.x.x:8080` 的 Keycloak）。如果没有该许可，非安全的签发者会在启动时被显著记录并在登录时被拒绝。 - **SCIM 2.0** — 生成一个组织范围内的 token（`create-scim-token`）并将你的 IdP 指向 `/scim/v2/Users` + `/scim/v2/Groups`。取消配置（`DELETE` 或 `PATCH active=false`）会立即吊销所有类型的凭证。名为 `tellur-admin` / `tellur-contributor` / `tellur-viewer` 的组驱动其成员的角色，并在成员身份变更时重新计算。 ### 连接开发者（`tellur login` + `tellur push`） 开发者无需复制 token 即可将其机器绑定到中心。`tellur login` 运行基于浏览器的设备授权流程 (RFC 8628)：CLI 打印一个短代码，打开中心的批准页面，已登录的成员对其进行确认。然后中心生成一个成员 API token，CLI 会将其存储在用户配置目录下（`~/.config/tellur/hosts.json`, `0600`）。它需要启用 SSO。 ``` tellur login --hub https://hub.example.com # opens a browser; approve the code tellur push # send this repo's events to the hub ``` `tellur push` 读取本地捕获的事件并将其转发到摄取 API，在 `.tellur/push_state.json` 中跟踪每个 `(hub, org, repo)` 的高水位标记，因此重复运行是**增量且幂等的**（没有重复数据）。中心、组织和 token 默认为存储的登录信息；可以使用 `--hub`、`--org`、`--repo`、`--token`（或 `TELLUR_HUB_URL` / `TELLUR_HUB_ORG` / `TELLUR_HUB_TOKEN`）覆盖它们中的任何一个。仓库名称默认为工作目录的名称，并在首次推送时在中心上创建。使用 `--dry-run` 进行预览，使用 `--reset` 从头重新推送。对于无人值守的 CI，跳过 `login` 并通过 `--token` / `TELLUR_HUB_TOKEN` 传递 `tellur-server admin create-token` token。 ### 团队 dashboard 该中心在 **`/app`** 提供了一个内置的 dashboard —— 一个嵌入在二进制文件中并由同源提供的 Svelte SPA，因此它会重用你的第一方 SSO 会话。在 `/auth/login` 登录，然后打开 `/app`。它在构建时被编译到二进制文件中，因此请在服务器之前构建 SPA（否则 `/app` 只会提供一个占位符；Docker 镜像会为你处理此操作）： ``` pnpm --dir crates/server/ui install pnpm --dir crates/server/ui build # → crates/server/ui/dist (embedded) cargo run -p tellur-server # /app now serves the real dashboard ``` 界面（参见 [`docs/proposals/TEAM_DASHBOARD_UI.md`](docs/proposals/TEAM_DASHBOARD_UI.md)）： - **概览** — 组织总计、AI 份额 + 审查覆盖率汇总、活动趋势，以及按审查缺口排名的仓库，只需一次往返即可完成（`GET .../overview`）。 - **仓库与文件溯源** — 每个仓库的统计信息和以元数据优先的归属槽。管理员可以从 **Source connection** 卡片将其仓库连接到相应的提供商（选择 GitHub/GitLab/Bitbucket + `owner/repo` + 分支 —— 无需学习模板语法），从而实现按范围的**深链接**和内联源代码视图。**公开**仓库直接从提供商在浏览器中获取（中心不存储/提供任何源代码）；**私有**仓库使用存储的、最小权限的 token，并通过中心的**受 SSRF 保护的 blob 代理**（`GET .../blob`）获取 —— token 永远不会离开中心。也可以通过 `tellur-server admin set-repo-source` 进行设置。 - **会话与重放** — 动态的基于会话的时间线：汇总统计（事件 / 持续时间 / 文件 / prompt），类别 + 参与者过滤器和搜索，以及按类型颜色编码的单事件节点（prompt / 文件 / 命令 /工具 / 测试 / git）。**当启用 prompt 摘录捕获时**，Prompt 会内联显示 —— 默认情况下，Tellur 仅存储 prompt *哈希*；在 `.tellur/config.yml` 中设置 `redaction.store_prompt_excerpt: true` 以同时保留经过敏感信息脱敏的、长度有限的摘录（适用于选择加入后捕获的活动）。 - **管理** — **策略**合规性（按严重程度划分的违规情况 + 一键重新评估），**人员与访问权限**（成员、SCIM 组、SSO/SCIM 健康状况），一个**审计日志**浏览器，以及一个**导出**控制台。 命令面板（**⌘K** / **Ctrl-K**）可在各个界面之间跳转，顶栏控件可切换主题（系统 / 浅色 / 深色）、密度（舒适 / 紧凑）和语言（英语 / 荷兰语）。 ## 开发 ``` cargo fmt --check cargo test cargo run -p tellur-cli -- doctor ``` Dashboard SPA (`crates/server/ui`)： ``` pnpm install pnpm check && pnpm test # svelte-check + vitest pnpm e2e # Playwright (real bundle, mocked /v1 API) ``` VS Code 扩展： ``` cd editor/tellur-vscode npm install npm run compile npm test npm run package ``` Tellur 的 VS Code 扩展支持 VS Code/Copilot 的 Bring Your Own Key (BYOK) 模型元数据以用于监视会话。在 VS Code 中通过 `Chat: Manage Language Models` 配置 BYOK，如果可用模型不止一个，则运行 `Tellur: Select VS Code AI Model`。`Tellur: Diagnose VS Code AI Models` 会显示 VS Code 向扩展公开了哪些模型，以及 Tellur 将附加到新监视会话的内容。 VS Code 没有公开允许一个扩展拦截来自其他聊天参与者的任意 Copilot/BYOK 聊天 prompt 的公共 API。对于 prompt 溯源，请使用 `Tellur: Record AI Prompt`；Tellur 会记录 SHA-256 prompt 哈希以及模型元数据，而不是原始 prompt 文本。 ## 路线图 本地 pipeline、多 agent 适配器和自托管中心（API、OIDC SSO、SCIM 用户 + 组配置、持久化导出、合规性快照、保留策略和完整的团队 dashboard）均已实现。正在进行和即将开展的工作： - **零接触溯源 + GitHub App** — 自动推送 `refs/notes/ai` 和后台中心同步，使开发者在安装后无需运行任何命令，外加一个可选的 GitHub App（安装 token 源代码访问权限、仓库发现、notes 收集器、PR 检查）。设计：[`docs/proposals/GITHUB_APP.md`](docs/proposals/GITHUB_APP.md)。 - 为 npm、Homebrew 和 GitHub Releases 提供**打包发行版**。 - 针对安全敏感型仓库的**更丰富的策略模板**。 - 随着更多工具公开稳定的本地生命周期钩子，提供**更广泛的 agent 覆盖范围**。 `tellur-core` 二进制文件是用于打包冒烟测试的内部诊断入口点。请使用 `tellur` 二进制文件进行正常的 CLI 工作流。 ## 贡献 请参见 [CONTRIBUTING.md](./CONTRIBUTING.md)。 ## 许可证 Apache-2.0 — 请参见 [LICENSE](./LICENSE)。

标签：AI辅助开发, DevSecOps, Rust, SOC Prime, 上游代理, 代码溯源, 可视化界面, 开发工具, 时序数据库, 网络流量审计, 通知系统