Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 1 addition & 2 deletions AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -55,8 +55,7 @@ Generic inspect DevTool for agent session logs. Not a harness. Not dsh Trajector
- A PR that changes shipped files under `apps/` or `packages/` carries a changeset under `.changeset/`; rules in `CONTRIBUTING.md#release-intent`. Do not edit generated changelogs or add a hand-written root `CHANGELOG.md`.
- Contribution workflow, Specs, and Plans live in `CONTRIBUTING.md`, `docs/specs/`, and `docs/plans/`. Do not copy the `technical-design-docs` skill into this repo.
- File and directory names are kebab-case, and a code file has at most 500 lines; rules in `CONTRIBUTING.md#file-conventions`.
- Every Spec and Plan ships with a `.zh-CN.md` reading copy in the same PR; rules in `CONTRIBUTING.md#bilingual-specs-and-plans`.
- The root README ships with a `README.zh-CN.md` reading copy in the same PR; other READMEs and templates have none. Rules in `CONTRIBUTING.md#bilingual-readme`.
- The root README, every document in `docs/guide/`, `docs/reference/`, `docs/architecture/`, and `docs/development/`, and every Spec and Plan ship with a `.zh-CN.md` reading copy updated in the same PR; every other document (`docs/README.md`, `docs/design/`, the other READMEs, and all templates) has none. Rules in `CONTRIBUTING.md#bilingual-documentation`.
- Keep changes scoped to the task. Do not commit local config, credentials, generated logs, temporary workspaces, build artifacts, or machine-specific paths.

## Review Evidence
Expand Down
26 changes: 7 additions & 19 deletions CONTRIBUTING.md
Original file line number Diff line number Diff line change
Expand Up @@ -85,30 +85,18 @@ The execution plan tells the implementer exactly what to do: preconditions, a co

Keep unknown owners, dates, and interfaces marked "unconfirmed". A plan may make feature-specific technical decisions, but it cannot silently override current architecture. At completion, migrate lasting constraints into current-state docs and tests, then delete the completed Spec and plan in the final delivery PR. Keep unfinished scope visible.

## Bilingual Specs And Plans
## Bilingual Documentation

Every active Spec and Plan has a Chinese reading copy beside it: `docs/specs/0001-foo.md` pairs with `docs/specs/0001-foo.zh-CN.md`, and `docs/plans/0001-foo.md` with `docs/plans/0001-foo.zh-CN.md`. The English file is the source of truth for review and implementation. The Chinese copy lets Chinese-speaking reviewers read the whole design.
These documents have a Chinese reading copy beside them, named with `.zh-CN.md` in place of `.md`: the root `README.md`, every document in `docs/guide/`, `docs/reference/`, `docs/architecture/`, and `docs/development/`, and every active Spec and Plan (`docs/specs/0001-foo.md` pairs with `docs/specs/0001-foo.zh-CN.md`). The English file is the source of truth for review and implementation. The Chinese copy lets Chinese-speaking users and reviewers read the same content. Every other document is English only, such as `AGENTS.md`, this file, `SECURITY.md`, `docs/README.md`, `docs/design/`, the other READMEs (such as `apps/cli/README.md`), and every template.

- The English file changes first; the Chinese copy follows in the same PR.
- The Chinese copy starts with `> 中文阅读版。以英文原文 <English path> 为准。`
- It keeps the English structure: the same headings at every level, the same scenario and decision IDs, the same table rows, and every code block and diagram copied unchanged.
- The Chinese copy starts with `> 中文阅读版。以英文原文 <English path> 为准。`, followed by a `<!-- source-blob: <hash> -->` line: the Git blob hash of the English file the copy was last checked against.
- It keeps the English structure: the same headings at every level in the same order, the same scenario and decision IDs, the same table rows and columns, the same list items and links, and every code block and diagram copied unchanged.
- A link to a document that has a Chinese copy points to the copy, and its anchor names the copy's Chinese heading; every other link stays as in English.
- It states the same content. It does not summarize, add, or settle an ambiguity the English leaves open.
- Chinese prose uses plain statements and noun-phrase headings. Identifiers, paths, commands, and field names stay as written in English.
- Templates and README files other than the root README have no Chinese copy; see [Bilingual README](#bilingual-readme).
- Chinese prose uses plain statements and noun-phrase headings, full-width punctuation, and the terms of the UI glossary at the top of `apps/web/src/i18n/dictionary.zh-CN.ts`; a UI label is quoted as the Chinese UI shows it. Identifiers, paths, commands, field names, and product names stay as written in English.

`node scripts/check-doc-translations.mjs` checks the pairing, the first line, heading counts per level, and code blocks. CI and the pre-commit hook run it. It cannot tell whether the prose says the same thing; reviewers check that.

## Bilingual README

The root `README.md` has one Chinese reading copy, `README.zh-CN.md`. English is the source of truth for review and implementation.

- The English file changes first; the Chinese copy follows in the same PR.
- The Chinese copy starts with `> 中文阅读版。以英文原文 README.md 为准。`
- It keeps the English structure: the same headings at every level, and every code block copied unchanged.
- It states the same content. It does not summarize, add, or settle an ambiguity the English leaves open.
- Chinese prose uses plain statements and noun-phrase headings. Identifiers, paths, commands, and field names stay as written in English.

`node scripts/check-doc-translations.mjs` checks the README pair along with the Spec and Plan pairs.
`node scripts/check-doc-translations.mjs` checks the pairing, the first line, headings, code blocks, tables, list items, links and anchors, and that no English file changed after its copy was recorded. CI and the pre-commit hook run it. When an English file changes, `git show <hash>` prints the text its copy last matched; carry the difference into the copy, then record it with `node scripts/check-doc-translations.mjs --write <English or Chinese path>...`. The check cannot tell whether the prose says the same thing; reviewers check that.

## Release Intent

Expand Down
42 changes: 22 additions & 20 deletions README.zh-CN.md
Original file line number Diff line number Diff line change
@@ -1,5 +1,7 @@
> 中文阅读版。以英文原文 README.md 为准。

<!-- source-blob: 70f6776a578532f6932fab5d6694271be6842d36 -->

<p align="center">
<a href="README.md">English</a> · <strong>简体中文</strong>
</p>
Expand All @@ -11,7 +13,7 @@
<h1 align="center">Estela</h1>

<p align="center">
<strong>Agent 会话的本地查看器:每个请求、模型看到的内容,以及花费。</strong>
<strong>代理会话的本地查看器:每个请求、模型看到的内容,以及花费。</strong>
</p>

<p align="center">
Expand All @@ -28,31 +30,31 @@
npx @rivus/estela
```

需要 Node.js 24 或更高版本,支持 macOS、Linux 和 Windows。它列出本机 Agent 的会话,并在浏览器中打开。任何数据都不会离开本机。
需要 Node.js 24 或更高版本,支持 macOS、Linux 和 Windows。它列出本机代理的会话,并在浏览器中打开。任何数据都不会离开本机。

## 用途

Agent 会保存详细的日志,但日志很难读。Agent 出错时,需要知道它当时实际看到了什么。Estela 仅凭日志回答三个问题:
代理会保存详细的日志,但日志很难读。代理出错时,需要知道它当时实际看到了什么。Estela 仅凭日志回答三个问题:

- **Agent 为什么这样做?** 对任意请求,Estela 重建模型收到的上下文:系统提示词、工具、之前的消息和当前轮次。
- **代理为什么这样做?** 对任意请求,Estela 重建模型收到的上下文:系统提示词、工具、之前的消息和当前轮次。
- **上下文压缩移除了什么?** 它显示压缩把哪些事件移出了模型的视野,并对比压缩前后的上下文。
- **Token 和钱花在哪里?** 它按请求、轮次、子 Agent 和会话显示记录的 Token 数及其标价。
- **Token 和钱花在哪里?** 它按请求、轮次、子代理和会话显示记录的 Token 数及其目录价。

日志未记录的内容显示为 `unavailable`,从不估算。

## 功能

- **会话浏览器。** 本机所有会话集中在一个列表中,最新的在前,显示轮次、请求、Token、时长,并标记上下文压缩、子 Agent 和失败的工具调用。可按 Agent、项目和标记过滤;可搜索标题和你自己输入的提示词。
- **时间线与事件列表。** 每个请求一根柱(高度为输入 Token),每个子 Agent 一行,上下文压缩处标出压缩前后的 Token;所有事件按顺序排列,可按轮次或按 Agent 分组。
- **Model saw。** 任意事件处的上下文,按槽位列出,附 Agent 记录的 Token 数和被压缩移除的事件。
- **Compare。** 并排对比两个请求的上下文:哪些事件进入了上下文、哪些被压缩隐藏,以及系统提示词或工具是否变化。
- **花费。** 按请求、轮次、子 Agent 和会话显示所记录 Token 的标价,以及缓存占比;不完整的合计会说明遗漏了多少个请求。
- **会话浏览器。** 本机所有会话集中在一个列表中,最新的在前,显示轮次、请求、Token、时长,并标记上下文压缩、子代理和失败的工具调用。可按代理、项目和标记过滤;可搜索标题和你自己输入的提示词。
- **时间线与事件列表。** 每个请求一根柱(高度为输入 Token),每个子代理一行,上下文压缩处标出压缩前后的 Token;所有事件按顺序排列,可按轮次或按代理分组。
- **模型所见。** 任意事件处的上下文,按槽位列出,附代理记录的 Token 数和被压缩移除的事件。
- **对比。** 并排对比两个请求的上下文:哪些事件进入了上下文、哪些被压缩隐藏,以及系统提示词或工具是否变化。
- **花费。** 按请求、轮次、子代理和会话显示所记录 Token 的目录价,以及缓存占比;不完整的合计会说明遗漏了多少个请求。
- **报告与导出。** 一个可分享的已脱敏 `index.html`,一个供 Harbor 使用的 ATIF v1.8 轨迹,一个供 Langfuse、LangSmith 或 Phoenix 使用的 OTLP/JSON trace。
- **MCP 工具。** `estela mcp` 让 Agent 找到之前的会话,并读取某个失败请求时模型看到的内容。
- **MCP 工具。** `estela mcp` 让代理找到之前的会话,并读取某个失败请求时模型看到的内容。

## 支持的 Agent
## 支持的代理

| Agent | 会话位置 |
| 代理 | 会话位置 |
|---|---|
| Claude Code | `~/.claude/projects/` |
| Codex | `~/.codex/sessions/`、`~/.codex/archived_sessions/` |
Expand All @@ -62,18 +64,18 @@ Agent 会保存详细的日志,但日志很难读。Agent 出错时,需要
| OpenCode | `~/.local/share/opencode/opencode.db` |
| Pi | `~/.pi/agent/sessions/` |

各 Agent 的 home 覆盖变量都会生效。各 Agent 日志记录的内容(系统提示词、工具定义、用量、子 Agent、上下文压缩)不同,见 [Supported agents](docs/guide/supported-agents.md)。
各代理的主目录覆盖变量都会生效。各代理日志记录的内容(系统提示词、工具定义、用量、子代理、上下文压缩)不同,见[支持的代理](docs/guide/supported-agents.zh-CN.md)。

## 隐私

Estela 在本地运行,绑定 `localhost`,只读取会话日志。它在 `~/.cache/rivus-estela/` 中保存一份未脱敏的缓存,包含会话标题、路径、数字,以及每个会话最多 200 条你输入的提示词,可随时删除。脱敏会替换你的 home 目录和部分 token 形式,但不会覆盖所有密钥;报告中仍包含会话文本和文件内容:分享报告前请先阅读。详见 [Privacy and redaction](docs/guide/privacy.md)。
Estela 在本地运行,绑定 `localhost`,只读取会话日志。它在 `~/.cache/rivus-estela/` 中保存一份未脱敏的缓存,包含会话标题、路径、数字,以及每个会话最多 200 条你输入的提示词,可随时删除。脱敏会替换你的主目录和部分令牌形式,但不会覆盖所有密钥;报告中仍包含会话文本和文件内容:分享报告前请先阅读。详见[隐私与脱敏](docs/guide/privacy.zh-CN.md)。

## 文档

- [User guide](docs/guide/README.md):入门、概念、工作区、报告与导出、MCP 工具、故障排查。
- [Public interface](docs/reference/public-interface.md):命令、选项、退出码、环境变量,以及 semver 覆盖的范围。
- [Export formats](docs/reference/export-formats.md):ATIF 和 OTLP 的映射。
- [Architecture](docs/architecture/overview.md)、[development setup](docs/development/setup.md)、[visual design](docs/design/README.md)、[contributing](CONTRIBUTING.md) 和 [security](SECURITY.md)。
- [用户指南](docs/guide/README.zh-CN.md):入门、概念、工作区、报告与导出、MCP 工具、故障排查。
- [公共接口](docs/reference/public-interface.zh-CN.md):命令、选项、退出码、环境变量,以及 semver 覆盖的范围。
- [导出格式](docs/reference/export-formats.zh-CN.md):ATIF 和 OTLP 的映射。
- [架构](docs/architecture/overview.zh-CN.md)、[开发设置](docs/development/setup.zh-CN.md)、[视觉设计](docs/design/README.md)、[贡献指南](CONTRIBUTING.md)和[安全策略](SECURITY.md)。

## 开发

Expand All @@ -89,7 +91,7 @@ node apps/cli/dist/bin.mjs

## 名字

_Estela_ 是西班牙语,指船驶过水面后留下的航迹。会话日志是 Agent 运行后留下的痕迹,Estela 读的就是它。包发布在 `@rivus` scope 下,_rivus_ 是拉丁语的“溪流”。
_Estela_ 是西班牙语,指船驶过水面后留下的航迹。会话日志是代理运行后留下的痕迹,Estela 读的就是它。包发布在 `@rivus` scope 下,_rivus_ 是拉丁语的“溪流”。

## 许可证

Expand Down
2 changes: 1 addition & 1 deletion docs/architecture/overview.md
Original file line number Diff line number Diff line change
Expand Up @@ -132,7 +132,7 @@ The SPA starts in report mode when it finds that element (`apps/web/src/shell/re

## Exports

`export-atif <path> [--out <file>]` and `export-otlp <path> [--out <file>]` (`apps/cli/src/export/write-export.ts`) load a session once and write one file: an ATIF v1.8 trajectory (`toAtif`, `packages/kernel/src/export-atif.ts`) or an OTLP/JSON `ExportTraceServiceRequest` (`toOtlp`, `packages/kernel/src/export-otlp.ts`). Both projections are pure functions over a checked `Trace` with no `node:*` import; the CLI redacts and writes. Both mappings are listed field by field in [Export formats](../reference/export-formats.md). ATIF: one step per user event, per `requestId` group, and per compaction (a system step with `extra.context_management`), subagent lanes as embedded `subagent_trajectories` referenced from the spawn step, fields ATIF has no place for under `extra.estela` with the canonical event ids. OTLP pins the semconv version named by `OTLP_SEMCONV_VERSION` (`gen-ai-dev/1.42.0-dev`; the GenAI conventions have no release yet, so a new pin is a deliberate change): one `invoke_agent` span per lane, one `chat` span per request with the `gen_ai.usage.*` counts and the model-visible surface from `reconstruct` as `gen_ai.input.messages` / `gen_ai.output.messages` / `gen_ai.system_instructions` / `gen_ai.tool.definitions`, and one `execute_tool` span per tool call. A trace with nothing the formats can hold (no user, agent, or system-prompt content) fails the export with that reason; a subagent lane with no exportable events is left out, its spawn ref with it. Exports are redacted like the server unless `ESTELA_REDACT=0`: a dataset or a tracing backend may need the unredacted bytes, so unlike a report an export can opt out. `node scripts/validate-exports.mjs` exports every agent's fixtures and runs Harbor's validator (`uv run --python 3.12 --with harbor`); it needs uv and the network, so CI runs only the structural ATIF check in `apps/cli/src/export/write-export.test.ts`.
`export-atif <path> [--out <file>]` and `export-otlp <path> [--out <file>]` (`apps/cli/src/export/write-export.ts`) load a session once and write one file: an ATIF v1.8 trajectory (`toAtif`, `packages/kernel/src/export-atif.ts`) or an OTLP/JSON `ExportTraceServiceRequest` (`toOtlp`, `packages/kernel/src/export-otlp.ts`). Both projections are pure functions over a checked `Trace` with no `node:*` import; the CLI redacts and writes. Both mappings are listed field by field in [Export formats](../reference/export-formats.md). ATIF: one step per user event, per `requestId` group, and per compaction (a system step with `extra.context_management`), subagent lanes as embedded `subagent_trajectories` referenced from the spawn step, fields ATIF has no place for under `extra.estela` with the canonical event ids. OTLP pins the semconv version named by `OTLP_SEMCONV_VERSION` (`gen-ai-dev/1.42.0-dev`; the GenAI conventions have no release yet, so a new pin is a deliberate change): one `invoke_agent` span per lane, one `chat` span per request with the `gen_ai.usage.*` counts and the model-visible surface from `reconstruct` as `gen_ai.input.messages` / `gen_ai.output.messages` / `gen_ai.system_instructions` / `gen_ai.tool.definitions`, and one `execute_tool` span per tool call. An ATIF export of a trace with nothing a step can hold (no user, agent, or system-prompt content) fails with that reason, and an ATIF export leaves out a subagent lane with no exportable events, its spawn ref with it. Exports are redacted like the server unless `ESTELA_REDACT=0`: a dataset or a tracing backend may need the unredacted bytes, so unlike a report an export can opt out. `node scripts/validate-exports.mjs` exports every agent's fixtures and runs Harbor's validator (`uv run --python 3.12 --with harbor`); it needs uv and the network, so CI runs only the structural ATIF check in `apps/cli/src/export/write-export.test.ts`.

## Bundle

Expand Down
Loading
Loading