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
2 changes: 1 addition & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -37,7 +37,7 @@ AgentMessage[] → transform_context() → convert_to_llm() → LangChain BaseMe
| `packages/pi-mcp/` | Optional extension `pi-mcp-py` (entry point `pi-mcp`): connects the MCP servers (stdio, http, sse) that an ACP client passes in `session/new`, one runner task per server, tools named `mcp__<server>__<tool>`, `/mcp` command. Core, harness and CLI have no MCP client; they hand the servers over as data (`ClientMcpServer`, `ExtensionAPI.client_mcp_servers`). Design: `docs/specs/2026-10-23-mcp-extension-design.md`. Its tests are left out of a run that did not install the package (the header says so) | — |
| `packaging/agent/` | Builds the agent as a one-file executable (PyInstaller; `build.py`, `zycode-agent.spec`, `entry.py`) and the smoke test over ACP with a fake model server (`smoke.py`). `.github/workflows/agent-binaries.yml` runs both on five platforms and attaches the archives to the GitHub Release after the `Release` workflow. A frozen build has no interpreter: `host.py` starts a frozen `child.py`, and only the OpenAI-format provider is in it. Design and the registry entry draft: `docs/specs/2026-10-31-agent-binaries.md` | — |
| `packages/pi-agent-cli/` | Standard-ACP CLI (`python -m pi_agent_cli`); config `agent.example.toml`, home `~/.pi-python`; TUI binary `zypi` under `tui/`. See [`packages/pi-agent-cli/AGENTS.md`](packages/pi-agent-cli/AGENTS.md) for spawn, config, first run (`--setup` and the terminal login that `initialize` offers to a client that can run one; `zypi` still gets `authMethods: []`), prompt pipeline, and the three permission modes `ask`, `auto` and `always-approve` (Auto: rules, and a model step for a `bash` call that no rule decides: `auto_rules.py`, `auto_classifier.py`, `auto_mode.py`, `permission_modes.py`; design `docs/specs/2026-11-02-auto-mode-design.md`; the pager offers all three, and a clean start is `ask`). The items on the ACP wire beyond standard ACP (`pi/session/delete`, `_meta.sessionId`, and others) are in the register `docs/specs/2026-11-05-acp-extension-registry.md` | — |
| `vscode/` | The VS Code extension `zycode.zycode` (TypeScript, `src/core/` has no `vscode` import). It is an ACP client and a chat view for zycode in VS Code: it starts the agent as a child process, shows permission questions and a diff for `write`/`edit`, runs the first-run setup in a terminal (a walkthrough, a banner and hints guide the first start; the agent's own `--setup` and `auth_required` carry it, no wire item and no agent change), lists past chats of the folder in a view (`session/list`, `session/load`, `pi/session/delete`), and offers the three permission modes `ask`, `auto` and `always-approve` in the chat menu (`always-approve` only after a modal warning, never restored for a new chat, a past chat or a restart, and not in an untrusted workspace; the `zycode.permissionMode` setting stays `ask`/`auto`; it moves the agent with the agent's own `pi/yolo_mode_changed`). The extension never writes `always-approve` through `set_config_option`. A Thinking menu shows `thinking_level` of `agent.toml`; agent 0.9.1 cannot change it live, so a change edits that one line (checked by parsing, after a modal), restarts the agent and reopens the chat (design section 7c). One VSIX per platform, each with the bundled `zycode-agent` binary of one Release (pin and sha256 in `agent-assets.json`). Not a Python package: pytest does not read it, and ruff reads only its three Python helpers (`scripts/python_licenses.py`, `test/support/fake_model.py`, `test/support/pty_answers.py`). `.github/workflows/vscode-extension.yml` runs `npm run check` and a `linux-x64` VSIX smoke test for a PR that changes it. `ci.yml` (Ruff, pytest) skips a PR that touches only `vscode/`, `docs/` and that workflow, with no `.py` file (a `paths` filter with `!` patterns; no check is required on `main`, so a skipped run blocks no merge). The same workflow publishes (Trusted Publishing, by hand on `main`, environment `vscode-publish`). 1.0.0 was the first stable release (the pre-release 0.1.0 was uploaded by hand; the 1.0.0 run, run `43181052994` on 2026-11-12, was the first real OIDC publish and worked on the first try on Open VSX and the Marketplace, five targets, no token; the record is in `vscode/RELEASING.md`; the owner tested the install of 1.0.0 and the update from 0.1.0 on Windows (2026-11-12), and the rest of the Windows flow, macOS and Linux in a real VS Code are not verified; stable = even minor, pre-release = odd minor). Do not rename that file or the environment: the registries name them. Local check: `cd vscode; npm run check`. Design: `docs/specs/2026-11-04-vscode-extension-design.md`; make and test a VSIX: `vscode/PACKAGING.md`; releases: `vscode/RELEASING.md` | — |
| `vscode/` | The VS Code extension `zycode.zycode` (TypeScript, `src/core/` has no `vscode` import). It is an ACP client and a chat view for zycode in VS Code: it starts the agent as a child process, shows permission questions and a diff for `write`/`edit`, runs the first-run setup in a terminal (a walkthrough, a banner and hints guide the first start; the agent's own `--setup` and `auth_required` carry it, no wire item and no agent change), lists past chats of the folder in a view (`session/list`, `session/load`, `pi/session/delete`), and offers the three permission modes `ask`, `auto` and `always-approve` in the chat menu (`always-approve` only after a modal warning, never restored for a new chat, a past chat or a restart, and not in an untrusted workspace; the `zycode.permissionMode` setting stays `ask`/`auto`; it moves the agent with the agent's own `pi/yolo_mode_changed`). The extension never writes `always-approve` through `set_config_option`. A Thinking menu shows `thinking_level` of `agent.toml`; agent 0.9.1 cannot change it live, so a change edits that one line (checked by parsing, after a modal), restarts the agent and reopens the chat (design section 7c). The menu has `max` only for an agent of `MAX_LEVEL_SINCE` (`src/core/thinking.ts`, 1.0.0) or later, because an older agent reads `max` as `off` and says nothing; check that number when the pin moves (`vscode/PACKAGING.md`). One VSIX per platform, each with the bundled `zycode-agent` binary of one Release (pin and sha256 in `agent-assets.json`). Not a Python package: pytest does not read it, and ruff reads only its three Python helpers (`scripts/python_licenses.py`, `test/support/fake_model.py`, `test/support/pty_answers.py`). `.github/workflows/vscode-extension.yml` runs `npm run check` and a `linux-x64` VSIX smoke test for a PR that changes it. `ci.yml` (Ruff, pytest) skips a PR that touches only `vscode/`, `docs/` and that workflow, with no `.py` file (a `paths` filter with `!` patterns; no check is required on `main`, so a skipped run blocks no merge). The same workflow publishes (Trusted Publishing, by hand on `main`, environment `vscode-publish`). 1.0.0 was the first stable release (the pre-release 0.1.0 was uploaded by hand; the 1.0.0 run, run `43181052994` on 2026-11-12, was the first real OIDC publish and worked on the first try on Open VSX and the Marketplace, five targets, no token; the record is in `vscode/RELEASING.md`; the owner tested the install of 1.0.0 and the update from 0.1.0 on Windows (2026-11-12), and the rest of the Windows flow, macOS and Linux in a real VS Code are not verified; stable = even minor, pre-release = odd minor). Do not rename that file or the environment: the registries name them. Local check: `cd vscode; npm run check`. Design: `docs/specs/2026-11-04-vscode-extension-design.md`; make and test a VSIX: `vscode/PACKAGING.md`; releases: `vscode/RELEASING.md` | — |
| `web/` | Product site for zycode, live at `https://zycode.dev` (static Astro, Node ≥ 22.23.4; English at `/`, Chinese at `/zh/`; Cloudflare Workers static assets, no server of ours). Not a Python package: ruff and pytest do not read it; `.github/workflows/web-ci.yml` runs `npm run check` and `npm run build` for a PR that changes `web/`. A merge to `main` that changes `web/` deploys to `zycode.dev` by itself (Cloudflare Workers Builds, not GitHub Actions). Its claims must stay equal to the README table "Status" and to the benchmark report, and `en.ts` / `zh.ts` keep the same keys. See [`web/README.md`](web/README.md) for commands, deploy, the domain, and the Cloudflare settings that are not in the repository | — |

### Invariants
Expand Down
6 changes: 4 additions & 2 deletions docs/DESIGN.md
Original file line number Diff line number Diff line change
Expand Up @@ -146,7 +146,9 @@ agent_start → turn_start → message_start(user) → message_end(user)

### 5.2 Thinking / Reasoning

`ThinkingLevel`(off/minimal/low/medium/high/xhigh)映射为 provider 参数:Anthropic `thinking.budget_tokens` + 联动 `max_tokens`;OpenAI `reasoning_effort`;DeepSeek 官方 API 经 `extra_body` 发 `thinking: enabled|disabled` 与 `reasoning_effort`(它默认开启思考,所以闸门关闭时显式发 `disabled`;网关不发。见 Phase 6 规格 §5.4)。Anthropic thinking 块流式捕获为 `ThinkingContent`(含 `signature` 用于多轮工具回放),以 `thinking_delta` 事件实时发射。DeepSeek 风格网关流式返回的 `reasoning_content`(或 `reasoning`)同样捕获:`provider="deepseek"` 由 `ChatDeepSeek` 保留,`provider="openai"` 由 `adapters/openai_reasoning.py` 的 `ChatOpenAI` 子类保留(普通 `ChatOpenAI` 会丢掉它;冻结版只有 openai provider,靠这个才能显示思考;该子类只保留流,不回传)。DeepSeek 官方 API 开启思考时,之前 assistant 消息的这部分在后续请求里按 `reasoning_content` 回传(不回传会 400;`adapters/deepseek_replay.py`,Phase 6 规格 §5.5),网关不回传。
`ThinkingLevel`(off/minimal/low/medium/high/xhigh/max)映射为 provider 参数:Anthropic `thinking.budget_tokens` + 联动 `max_tokens`;OpenAI `reasoning_effort`;DeepSeek 官方 API 经 `extra_body` 发 `thinking: enabled|disabled` 与 `reasoning_effort`(它默认开启思考,所以闸门关闭时显式发 `disabled`;网关不发。见 Phase 6 规格 §5.4)。Anthropic thinking 块流式捕获为 `ThinkingContent`(含 `signature` 用于多轮工具回放),以 `thinking_delta` 事件实时发射。DeepSeek 风格网关流式返回的 `reasoning_content`(或 `reasoning`)同样捕获:`provider="deepseek"` 由 `ChatDeepSeek` 保留,`provider="openai"` 由 `adapters/openai_reasoning.py` 的 `ChatOpenAI` 子类保留(普通 `ChatOpenAI` 会丢掉它;冻结版只有 openai provider,靠这个才能显示思考;该子类只保留流,不回传)。DeepSeek 官方 API 开启思考时,之前 assistant 消息的这部分在后续请求里按 `reasoning_content` 回传(不回传会 400;`adapters/deepseek_replay.py`,Phase 6 规格 §5.5),网关不回传。

`max` 是 `xhigh` 之上的等级(上游 pi 在 v0.80.6 加入;pi 靠每个模型的 `thinkingLevelMap` 决定哪些等级可用,本适配器没有这张表)。它在 OpenAI 格式(含网关)和 DeepSeek 官方 API 上原样发 `"max"`;Anthropic 的预算形式没有比 `xhigh` 更高的一档,所以 `max` 用 `xhigh` 的预算(40000)。适配器不按模型降级:模型不接受 `max` 时,服务端返回错误,错误会显示出来。三张映射表(`_ANTHROPIC_BUDGET`、`_OPENAI_EFFORT`、`_DEEPSEEK_EFFORT`)必须列出每一个等级(测试检查):缺一个键,请求里就没有推理参数,模型会静默不思考。`agent.toml` 里写了不认识的等级时,agent 用 `off`,并在会话开始时告诉用户。Anthropic 的文档说,较新的模型(Claude 4.7 及以后)会拒绝 `budget_tokens`,要用自适应思考加 `effort`;本适配器只发预算形式(未对真实 API 验证;这是另一项工作)。

### 5.3 跨 Provider 消息回放 (`transform.py`)

Expand All @@ -161,7 +163,7 @@ messages → normalize_tool_call_ids → downgrade_thinking → strip_unsupporte
### 5.4 流式重试与失控保护

- **重试**:首 token 前指数退避 + 抖动(`Retry-After` 感知),可配 `max_retries`
- **`max_turns`**:超限抛 `MaxTurnsExceededError`,Agent 转为 error-stop assistant message
- **`max_turns`**:超限抛 `MaxTurnsExceededError`,Agent 转为 error-stop assistant message。错误文本以 `MAX_TURNS_MESSAGE` 开头;ACP CLI 靠它把这次停止报成 `max_turn_requests`(其他错误仍是 `end_turn`)。默认值是 `None`(不限制)
- **`tool_timeout`**:单工具超时 → error tool result(LLM 可见可自纠)

### 5.5 Guardrail Hooks 与可观测性
Expand Down
1 change: 1 addition & 0 deletions docs/TUI-AND-CODE-AGENT.md
Original file line number Diff line number Diff line change
Expand Up @@ -117,6 +117,7 @@ provider = "deepseek" # or "openai", "anthropic"
id = "deepseek-ai/DeepSeek-V4-Flash"
api_key_env = "REAL_LLM_API_KEY" # env var holding the key for `provider` only
base_url = "https://api.siliconflow.cn/v1" # for OpenAI-compatible gateways
context_window = 128000 # tokens; the agent then tells a client how full the context is (ACP `usage_update`)

[skills]
# ".pi/skills" is relative to the project, so it loads only for a trusted project (see [extensions]).
Expand Down
Loading
Loading