zettcode 0.1.2__tar.gz → 0.1.4__tar.gz

{zettcode-0.1.2 → zettcode-0.1.4}/.gitignore

@@ -4,6 +4,7 @@
 *.egg-info/
 build/
 dist/
+.smoke/
 .coverage
 **/.pytest_cache/
 **/.ruff_cache/

zettcode-0.1.4/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.5
+Name: zettcode
+Version: 0.1.4
+Summary: A focused terminal coding agent powered by zett-agent
+Project-URL: Repository, https://github.com/Chang-LeHung/zettcode
+Project-URL: Issues, https://github.com/Chang-LeHung/zettcode/issues
+Author: Chang-LeHung
+License-Expression: MIT
+License-File: LICENSE
+Keywords: agent,coding-agent,llm,terminal,tui
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: Microsoft :: Windows :: Windows 10
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: exceptiongroup<2,>=1.2; python_version < '3.11'
+Requires-Dist: pydantic<3,>=2
+Requires-Dist: pyperclip<2,>=1.9
+Requires-Dist: setproctitle<2,>=1.3.7; os_name == 'posix'
+Requires-Dist: tiktoken<1,>=0.12
+Requires-Dist: tomli<3,>=2; python_version < '3.11'
+Requires-Dist: truststore<1,>=0.10
+Requires-Dist: wcwidth<1,>=0.2
+Requires-Dist: zett-agent<0.2,>=0.1.14
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="docs/public/logo.svg" width="88" height="88" alt="ZettCode pixel robot with a warm heart" />
+</p>
+<h1 align="center">ZettCode</h1>
+<p align="center"><strong>Your terminal. Your coding partner.</strong></p>
+<p align="center">A focused coding agent that reads your project, shows its work, and keeps you in control.</p>
+<p align="center">
+  <strong>English</strong> · <a href="README.zh-CN.md">简体中文</a><br />
+  <a href="https://chang-lehung.github.io/zettcode/guide/getting-started">Get started</a> ·
+  <a href="https://chang-lehung.github.io/zettcode/">Documentation</a> ·
+  <a href="https://chang-lehung.github.io/zettcode/guide/commands">Commands</a>
+</p>
+
+<p align="center">
+  <img src="docs/public/terminal.svg" width="1000" alt="ZettCode showing a task, thinking, file reads, a code edit, passing tests, and a Markdown answer" />
+</p>
+<p align="center"><sub>Illustrative conversation, rendered with ZettCode’s actual terminal widgets.</sub></p>
+
+## Get running
+
+You need **Python 3.10+**, a UTF-8 terminal, and an **OpenAI-compatible API**
+(or Anthropic's **Messages API**).
+Works on macOS, Linux, and Windows (use Windows Terminal).
+
+### 1. Install
+
+```bash
+uv tool install zettcode
+# or: pip install zettcode
+```
+
+### 2. Connect a model
+
+Create `~/.zettcode/config.toml` (and its parent directory) with one model:
+
+```toml
+[[models]]
+model = "deepseek-v4-pro"             # the model id sent to DeepSeek
+display_model = "DeepSeek Pro"        # the name shown in ZettCode
+token = "sk-..."                      # replace with your DeepSeek API key
+base_url = "https://api.deepseek.com"  # DeepSeek's OpenAI-compatible API root
+context_window = 1000000               # verify against the endpoint's current limits
+multimodal = false                    # this model accepts text, not images
+```
+
+Get a key from the [DeepSeek platform](https://platform.deepseek.com/), not from
+the chat website. Alternatively, omit `token` and set `OPENAI_API_KEY` to that
+key. Add more `[[models]]` entries to switch with `/model`; the first is selected
+at startup. See the
+[configuration reference](https://chang-lehung.github.io/zettcode/guide/config)
+for complete examples, defaults, and troubleshooting.
+
+### 3. Start a task
+
+```bash
+cd /path/to/project
+zettcode
+# or: zettcode --workspace /path/to/project
+```
+
+Describe a change and press **Enter**. Type `/` for commands, `@` to reference a
+skill, and **Ctrl-C** to stop a request. **Ctrl-D** with an empty composer exits
+and prints the command to resume your session.
+
+## Built for the way you work
+
+| | |
+| --- | --- |
+| **See every step** | Reasoning, answers, and tool calls stream as readable rows — not raw JSON. |
+| **Keep the decision** | Review shell commands before they run. When the agent needs your input, choose an option or type an answer. |
+| **Keep moving** | Send a steering message during a reply. Use `/btw` for a side question that stays out of later context. |
+| **Come back later** | `/resume` restores a conversation; `/export` saves a readable HTML record. |
+| **Understand the context** | Monitor token usage and caching, inspect `/context`, and compact when needed. |
+| **Bring your tools** | Use project `AGENTS.md` instructions, skills, MCP servers, and Python plugins. |
+
+The palette follows your terminal’s background, or your own `theme.toml`.
+Select and copy text, scroll through answers, and paste images when your model
+supports them.
+
+## Find your next step
+
+The **[user guide](https://chang-lehung.github.io/zettcode/guide/overview)** is
+available in English and [简体中文](https://chang-lehung.github.io/zettcode/zh/guide/overview).
+
+| First time | Everyday use | Configuration & extensions |
+| --- | --- | --- |
+| [Getting started](https://chang-lehung.github.io/zettcode/guide/getting-started) | [Keys & mouse](https://chang-lehung.github.io/zettcode/guide/keys) | [Configuration](https://chang-lehung.github.io/zettcode/guide/config) |
+| [The interface](https://chang-lehung.github.io/zettcode/guide/interface) | [Commands](https://chang-lehung.github.io/zettcode/guide/commands) | [Models & context](https://chang-lehung.github.io/zettcode/guide/models) |
+| [Problems & questions](https://chang-lehung.github.io/zettcode/guide/faq) | [Sessions](https://chang-lehung.github.io/zettcode/guide/sessions) | [Project instructions](https://chang-lehung.github.io/zettcode/guide/instructions) |
+| | | [Skills & MCP](https://chang-lehung.github.io/zettcode/guide/skills-and-mcp) · [Plugins](https://chang-lehung.github.io/zettcode/guide/plugins) |
+
+## Development
+
+```bash
+uv sync                         # install dependencies
+make check                      # Ruff, mypy, and tests
+make hooks                      # enforce mypy before commits
+make demo                       # browse terminal widgets
+make docs                       # preview the user guide locally
+uv run zettcode --workspace .    # run from the checkout
+```
+
+ZettCode provides the terminal application; the agent runtime is
+[`zett-agent`](https://github.com/Chang-LeHung/zett-agent). Contributor notes and
+invariants live in [`AGENTS.md`](AGENTS.md) and
+[`docs/internal/`](docs/internal/), separately from the user guide. See
+[`docs/internal/site-design.md`](docs/internal/site-design.md) for preview and
+asset-generation instructions.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

zettcode-0.1.4/README.md

@@ -0,0 +1,112 @@
+<p align="center">
+  <img src="docs/public/logo.svg" width="88" height="88" alt="ZettCode pixel robot with a warm heart" />
+</p>
+<h1 align="center">ZettCode</h1>
+<p align="center"><strong>Your terminal. Your coding partner.</strong></p>
+<p align="center">A focused coding agent that reads your project, shows its work, and keeps you in control.</p>
+<p align="center">
+  <strong>English</strong> · <a href="README.zh-CN.md">简体中文</a><br />
+  <a href="https://chang-lehung.github.io/zettcode/guide/getting-started">Get started</a> ·
+  <a href="https://chang-lehung.github.io/zettcode/">Documentation</a> ·
+  <a href="https://chang-lehung.github.io/zettcode/guide/commands">Commands</a>
+</p>
+
+<p align="center">
+  <img src="docs/public/terminal.svg" width="1000" alt="ZettCode showing a task, thinking, file reads, a code edit, passing tests, and a Markdown answer" />
+</p>
+<p align="center"><sub>Illustrative conversation, rendered with ZettCode’s actual terminal widgets.</sub></p>
+
+## Get running
+
+You need **Python 3.10+**, a UTF-8 terminal, and an **OpenAI-compatible API**
+(or Anthropic's **Messages API**).
+Works on macOS, Linux, and Windows (use Windows Terminal).
+
+### 1. Install
+
+```bash
+uv tool install zettcode
+# or: pip install zettcode
+```
+
+### 2. Connect a model
+
+Create `~/.zettcode/config.toml` (and its parent directory) with one model:
+
+```toml
+[[models]]
+model = "deepseek-v4-pro"             # the model id sent to DeepSeek
+display_model = "DeepSeek Pro"        # the name shown in ZettCode
+token = "sk-..."                      # replace with your DeepSeek API key
+base_url = "https://api.deepseek.com"  # DeepSeek's OpenAI-compatible API root
+context_window = 1000000               # verify against the endpoint's current limits
+multimodal = false                    # this model accepts text, not images
+```
+
+Get a key from the [DeepSeek platform](https://platform.deepseek.com/), not from
+the chat website. Alternatively, omit `token` and set `OPENAI_API_KEY` to that
+key. Add more `[[models]]` entries to switch with `/model`; the first is selected
+at startup. See the
+[configuration reference](https://chang-lehung.github.io/zettcode/guide/config)
+for complete examples, defaults, and troubleshooting.
+
+### 3. Start a task
+
+```bash
+cd /path/to/project
+zettcode
+# or: zettcode --workspace /path/to/project
+```
+
+Describe a change and press **Enter**. Type `/` for commands, `@` to reference a
+skill, and **Ctrl-C** to stop a request. **Ctrl-D** with an empty composer exits
+and prints the command to resume your session.
+
+## Built for the way you work
+
+| | |
+| --- | --- |
+| **See every step** | Reasoning, answers, and tool calls stream as readable rows — not raw JSON. |
+| **Keep the decision** | Review shell commands before they run. When the agent needs your input, choose an option or type an answer. |
+| **Keep moving** | Send a steering message during a reply. Use `/btw` for a side question that stays out of later context. |
+| **Come back later** | `/resume` restores a conversation; `/export` saves a readable HTML record. |
+| **Understand the context** | Monitor token usage and caching, inspect `/context`, and compact when needed. |
+| **Bring your tools** | Use project `AGENTS.md` instructions, skills, MCP servers, and Python plugins. |
+
+The palette follows your terminal’s background, or your own `theme.toml`.
+Select and copy text, scroll through answers, and paste images when your model
+supports them.
+
+## Find your next step
+
+The **[user guide](https://chang-lehung.github.io/zettcode/guide/overview)** is
+available in English and [简体中文](https://chang-lehung.github.io/zettcode/zh/guide/overview).
+
+| First time | Everyday use | Configuration & extensions |
+| --- | --- | --- |
+| [Getting started](https://chang-lehung.github.io/zettcode/guide/getting-started) | [Keys & mouse](https://chang-lehung.github.io/zettcode/guide/keys) | [Configuration](https://chang-lehung.github.io/zettcode/guide/config) |
+| [The interface](https://chang-lehung.github.io/zettcode/guide/interface) | [Commands](https://chang-lehung.github.io/zettcode/guide/commands) | [Models & context](https://chang-lehung.github.io/zettcode/guide/models) |
+| [Problems & questions](https://chang-lehung.github.io/zettcode/guide/faq) | [Sessions](https://chang-lehung.github.io/zettcode/guide/sessions) | [Project instructions](https://chang-lehung.github.io/zettcode/guide/instructions) |
+| | | [Skills & MCP](https://chang-lehung.github.io/zettcode/guide/skills-and-mcp) · [Plugins](https://chang-lehung.github.io/zettcode/guide/plugins) |
+
+## Development
+
+```bash
+uv sync                         # install dependencies
+make check                      # Ruff, mypy, and tests
+make hooks                      # enforce mypy before commits
+make demo                       # browse terminal widgets
+make docs                       # preview the user guide locally
+uv run zettcode --workspace .    # run from the checkout
+```
+
+ZettCode provides the terminal application; the agent runtime is
+[`zett-agent`](https://github.com/Chang-LeHung/zett-agent). Contributor notes and
+invariants live in [`AGENTS.md`](AGENTS.md) and
+[`docs/internal/`](docs/internal/), separately from the user guide. See
+[`docs/internal/site-design.md`](docs/internal/site-design.md) for preview and
+asset-generation instructions.
+
+## License
+
+MIT. See [`LICENSE`](LICENSE).

zettcode-0.1.4/README.zh-CN.md

@@ -0,0 +1,106 @@
+<p align="center">
+  <img src="docs/public/logo.svg" width="88" height="88" alt="ZettCode 像素机器人，中间是一颗暖色的心" />
+</p>
+<h1 align="center">ZettCode</h1>
+<p align="center"><strong>你的终端。你的编码伙伴。</strong></p>
+<p align="center">专注的编码智能体：读懂项目、展示过程，把决定权留给你。</p>
+<p align="center">
+  <a href="README.md">English</a> · <strong>简体中文</strong><br />
+  <a href="https://chang-lehung.github.io/zettcode/zh/guide/getting-started">快速开始</a> ·
+  <a href="https://chang-lehung.github.io/zettcode/zh/">使用文档</a> ·
+  <a href="https://chang-lehung.github.io/zettcode/zh/guide/commands">命令参考</a>
+</p>
+
+<p align="center">
+  <img src="docs/public/terminal.svg" width="1000" alt="ZettCode 依次展示任务、思考、读文件、改代码、通过的测试和 Markdown 回答" />
+</p>
+<p align="center"><sub>示例对话由 ZettCode 的实际终端组件渲染。</sub></p>
+
+## 先跑起来
+
+需要 **Python 3.10+**、支持 UTF-8 的终端和 **OpenAI 兼容接口**（或 Anthropic 的 **Messages API**）。
+支持 macOS、Linux 和 Windows（请使用 Windows Terminal）。
+
+### 1. 安装
+
+```bash
+uv tool install zettcode
+# 或者：pip install zettcode
+```
+
+### 2. 连接模型
+
+创建 `~/.zettcode/config.toml`（以及父目录），先配置一个模型：
+
+```toml
+[[models]]
+model = "deepseek-v4-pro"             # 发给 DeepSeek 的模型 id
+display_model = "DeepSeek Pro"        # ZettCode 界面中显示的名字
+token = "sk-..."                      # 替换成你的 DeepSeek API key
+base_url = "https://api.deepseek.com"  # DeepSeek 的 OpenAI 兼容接口根地址
+context_window = 1000000               # 以接入点当前公布的实际限制为准
+multimodal = false                    # 这个模型接受文本，不接受图片
+```
+
+在 [DeepSeek 开放平台](https://platform.deepseek.com/)创建 API key，不是聊天网页的登录信息。
+也可以省略 `token`，改用 `OPENAI_API_KEY` 环境变量保存这个 key。
+添加更多 `[[models]]`，就能用 `/model` 切换；启动时默认选择第一项。
+完整示例、默认值和排错步骤见[配置参考](https://chang-lehung.github.io/zettcode/zh/guide/config)。
+
+### 3. 发出任务
+
+```bash
+cd /path/to/project
+zettcode
+# 或者：zettcode --workspace /path/to/project
+```
+
+描述要改什么，按 **Enter**。`/` 打开命令菜单，`@` 引用 skill，**Ctrl-C** 停止请求。
+输入框为空时按 **Ctrl-D** 退出，终端会打印恢复当前会话的命令。
+
+## 按你的方式工作
+
+| | |
+| --- | --- |
+| **看清每一步** | 思考、回答和工具调用实时呈现为可读的行，不是原始 JSON。 |
+| **决定权在你手上** | 执行 shell 命令前先审阅；智能体需要你的决定时，可以选选项，也可以打字回答。 |
+| **工作不中断** | 回复过程中发送 steering（引导）消息；用 `/btw` 问一句，不让它进入后续上下文。 |
+| **随时接着做** | `/resume` 恢复对话，`/export` 导出便于阅读的 HTML。 |
+| **看懂上下文** | 查看 token 与缓存统计，用 `/context` 检查占用，在需要时压缩。 |
+| **接入你的工具** | 使用项目 `AGENTS.md` 指令、skills、MCP 服务器和 Python 插件。 |
+
+主题跟随终端背景，也可以使用你自己的 `theme.toml`。
+选中复制文字、滚动查看回答；模型支持多模态时，还能粘贴图片。
+
+## 找到你的下一步
+
+**[用户指南](https://chang-lehung.github.io/zettcode/zh/guide/overview)** 提供简体中文与
+[English](https://chang-lehung.github.io/zettcode/guide/overview) 两个版本。
+
+| 第一次使用 | 日常使用 | 配置与扩展 |
+| --- | --- | --- |
+| [快速开始](https://chang-lehung.github.io/zettcode/zh/guide/getting-started) | [快捷键与鼠标](https://chang-lehung.github.io/zettcode/zh/guide/keys) | [配置参考](https://chang-lehung.github.io/zettcode/zh/guide/config) |
+| [认识界面](https://chang-lehung.github.io/zettcode/zh/guide/interface) | [命令参考](https://chang-lehung.github.io/zettcode/zh/guide/commands) | [模型与上下文](https://chang-lehung.github.io/zettcode/zh/guide/models) |
+| [常见问题](https://chang-lehung.github.io/zettcode/zh/guide/faq) | [会话管理](https://chang-lehung.github.io/zettcode/zh/guide/sessions) | [项目指令](https://chang-lehung.github.io/zettcode/zh/guide/instructions) |
+| | | [Skills 与 MCP](https://chang-lehung.github.io/zettcode/zh/guide/skills-and-mcp) · [插件](https://chang-lehung.github.io/zettcode/zh/guide/plugins) |
+
+## 开发
+
+```bash
+uv sync                         # 安装依赖
+make check                      # Ruff、mypy 与测试
+make hooks                      # 每次提交前强制检查 mypy
+make demo                       # 浏览终端组件
+make docs                       # 本地预览使用文档
+uv run zettcode --workspace .    # 从源码运行
+```
+
+ZettCode 提供终端应用，智能体运行时来自
+[`zett-agent`](https://github.com/Chang-LeHung/zett-agent)。贡献者约定和不变量放在
+[`AGENTS.md`](AGENTS.md) 与 [`docs/internal/`](docs/internal/)，不进入用户指南。
+本地预览、重新生成效果图的方法见
+[`docs/internal/site-design.md`](docs/internal/site-design.md)。
+
+## 许可证
+
+MIT，见 [`LICENSE`](LICENSE)。

{zettcode-0.1.2 → zettcode-0.1.4}/pyproject.toml

@@ -24,10 +24,29 @@ classifiers = [
 dependencies = [
   # The stdlib gained both of these in 3.11; older runtimes take the backports.
   "exceptiongroup>=1.2,<2; python_version < '3.11'",
+  # Imported directly by the session store's record and metadata codecs, so it
+  # is declared here rather than borrowed from the runtime that brings it today.
+  "pydantic>=2,<3",
   "pyperclip>=1.9,<2",
+  "setproctitle>=1.3.7,<2; os_name == 'posix'",
+  # The counter behind ``/context`` measures a request with it, and imports it
+  # itself: the floor matches the runtime's, so neither resolver has to fight.
+  "tiktoken>=0.12,<1",
   "tomli>=2,<3; python_version < '3.11'",
+  # The system trust store, so the release check works behind a proxy.
+  "truststore>=0.10,<1",
   "wcwidth>=0.2,<1",
-  "zett-agent==0.1.10",
+  # A range, not a pin: 0.1.13 is the oldest runtime whose tool argument schemas
+  # are self-contained — Pydantic's ``$defs``/``$ref`` are expanded when the
+  # schema is built — and a gateway that refuses to resolve a pointer otherwise
+  # answers 400 to every request on its Messages route. It also keeps the two
+  # the floor below it was raised for: the shell tool called ``bash``, which this
+  # client's phrasing, colours, and approval path are keyed on, and SQLAlchemy,
+  # tiktoken, and httpx behind their first use, so warming a runtime costs less
+  # than it did. An exact pin would make zettcode fight every other tool that
+  # shares the dependency — including an upgrade of zett-agent itself, which pip
+  # would downgrade to satisfy it.
+  "zett-agent>=0.1.14,<0.2",
 ]
 
 [project.scripts]

{zettcode-0.1.2 → zettcode-0.1.4}/src/zettcode/__init__.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING
 
 #: The one place the version is written. ``pyproject.toml`` reads it from here
 #: and the release workflow checks the tag against it, so a bump is one edit.
-__version__ = "0.1.2"
+__version__ = "0.1.4"
 
 #: Where each public name lives; read by :func:`__getattr__` on first use.
 _EXPORTS = {

{zettcode-0.1.2 → zettcode-0.1.4}/src/zettcode/app/agent/__init__.py

@@ -7,7 +7,7 @@ from typing import TYPE_CHECKING
 
 #: Where each public name lives; read by :func:`__getattr__` on first use.
 _EXPORTS = {
-    "Entry": ".transcript",
+    "Entry": ".entries",
     "Transcript": ".transcript",
     "TranscriptProjector": ".projection",
     "ZettCodeAgent": ".agent",
@@ -17,9 +17,10 @@ _EXPORTS = {
 
 if TYPE_CHECKING:  # pragma: no cover - for type checkers, not the runtime
     from .agent import ZettCodeAgent
+    from .entries import Entry
     from .projection import TranscriptProjector
     from .runtime import ZettCodeRuntime
-    from .transcript import Entry, Transcript
+    from .transcript import Transcript
 
 
 def __getattr__(name: str) -> object: