tina-python 0.7.0__tar.gz → 0.7.2__tar.gz

{tina_python-0.7.0/tina_python.egg-info → tina_python-0.7.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tina-python
-Version: 0.7.0
+Version: 0.7.2
 Summary: tina is in your computer!
 Home-page: https://gitee.com/wang-churi/tina
 Author: 王出日
@@ -18,7 +18,7 @@ License-File: LICENSE
 Requires-Dist: httpx
 Requires-Dist: python-dotenv
 Provides-Extra: tui
-Requires-Dist: tina-tui>=0.1.0; extra == "tui"
+Requires-Dist: tina-tui>=0.2.0; extra == "tui"
 Provides-Extra: multi-agent
 Requires-Dist: tina-multi-agent>=0.1.0; extra == "multi-agent"
 Provides-Extra: mcp
@@ -28,7 +28,7 @@ Requires-Dist: pytest>=9.0; extra == "test"
 Requires-Dist: pytest-asyncio>=1.4; extra == "test"
 Requires-Dist: pytest-cov>=7.0; extra == "test"
 Provides-Extra: all
-Requires-Dist: tina-tui>=0.1.0; extra == "all"
+Requires-Dist: tina-tui>=0.2.0; extra == "all"
 Requires-Dist: tina-multi-agent>=0.1.0; extra == "all"
 Requires-Dist: mcp>=2.0; extra == "all"
 Dynamic: author
@@ -53,10 +53,13 @@ pip install tina-python
 # 如果需要使用 MCP（模型上下文协议）服务
 pip install tina-python[mcp]
 
-# 如果需要 TUI 终端界面
+# 如果需要 TUI 终端界面（独立发行包 tina-tui）
 pip install tina-python[tui]
 
-# 一次装齐所有可选功能（TUI + MCP）
+# 如果需要多 Agent 环境 + Web 调试控制台（独立发行包 tina-multi-agent）
+pip install tina-python[multi-agent]
+
+# 一次装齐所有可选功能（TUI + 多 Agent + MCP）
 pip install tina-python[all]
 
 # 如果需要运行测试
@@ -72,7 +75,7 @@ from tina.llm import BaseAPI
 # 1. 实例化大模型（支持通过 tina.env 文件配置）
 llm = BaseAPI(
     api_key="your-api-key",
-    base_url="https://api.openai.com/v1/chat/completions",
+    base_url="https://api.openai.com/v1",
     model="gpt-4o"
 )
 
@@ -113,7 +116,7 @@ for chunk in result:
 - [四、MCP 支持 —— 模型上下文协议](#四mcp-支持--模型上下文协议)
 - [五、多模态支持](#五多模态支持)
 - [六、快速开发工具](#六快速开发工具)
-- [6.5 终端界面 TUI（可选扩展）](#65-终端界面-tui可选扩展)
+- [七、拓展包（可选）](#七拓展包可选)
 
 ---
 
@@ -141,7 +144,8 @@ tina 是一个轻量、模块化的 AI 智能体框架，专注于让开发者
 | **MCPClient** | MCP 集成 | 连接 MCP 服务器生态（stdio/SSE） |
 | **ContextManager** | 上下文管理 | 滚动窗口策略，自动截断 |
 | **AgentEvents** | 事件系统 | 贯穿 Agent 生命周期的回调钩子 |
-| **TUI（可选）** | 终端界面 | 测试你写的 Agent 的交互控制台，也可当作自己的 TUI 使用 |
+| **TUI（可选）** | 终端界面 | 独立包 `tina-tui`：测试 Agent 的交互控制台，也可当作自己的 TUI 使用 |
+| **多 Agent（可选）** | 多 Agent 环境 | 独立包 `tina-multi-agent`：消息总线 + Web 调试控制台 |
 
 ---
 
@@ -160,7 +164,7 @@ llm = BaseAPI()
 # 或者：手动传入参数
 llm = BaseAPI(
     api_key="your-api-key",
-    base_url="https://api.openai.com/v1/chat/completions",
+    base_url="https://api.openai.com/v1",
     model="gpt-4o"
 )
 ```
@@ -168,11 +172,11 @@ llm = BaseAPI(
 `tina.env` 文件示例：
 ```env
 LLM_API_KEY="your-api-key"
-BASE_URL="https://api.openai.com/v1/chat/completions"
+BASE_URL="https://api.openai.com/v1"
 MODEL_NAME="gpt-4o"
 ```
 
-> **注意**：`base_url` 需要包含完整的 `/chat/completions` 路由，tina 不会自动补充。
+> **base_url 规则（0.7.0 起）**：只写服务根地址即可（如 `https://api.openai.com/v1`），tina 会自动补上 `/chat/completions`；写完整地址（`.../chat/completions`）也依然兼容。旧文档要求"必须自带 `/chat/completions`"的说法已作废。
 
 ### 1.2 非流式调用
 
@@ -707,7 +711,7 @@ tina 支持通过 MCP（Model Context Protocol）连接外部工具生态。
 pip install tina-python[mcp]
 ```
 
-> 想一次装齐所有可选功能（TUI + MCP）：`pip install tina-python[all]`
+> 想一次装齐所有可选功能（TUI + 多 Agent + MCP）：`pip install tina-python[all]`
 
 ### 4.2 使用 MCP 客户端
 
@@ -898,55 +902,7 @@ message = build_multimodal_message(
 
 tina 提供了一些开箱即用的工具函数和工具包，帮助你快速搭建应用。
 
-### 6.1 系统工具包 `system_tools`
-
-tina 自带一套系统工具包，包含文件操作、代码执行等常用功能：
-
-```python
-from tina import Agent, Tools
-from tina.llm import BaseAPI
-from tina.utils.system_tools import system_tools
-
-tools = Tools(name="my_tools")
-tools += system_tools  # 添加 tina 自带的系统工具包（工具集需命名）
-
-agent = Agent(
-    llm=BaseAPI(),
-    tools=tools,
-    system_prompt="你是一个系统助手，可以帮助我管理文件和执行代码"
-)
-
-result = agent.predict(instruction="帮我看看当前目录下有哪些文件", stream=True)
-for chunk in result:
-    print(chunk.content, end="")
-```
-
-**内置工具一览：**
-
-| 工具名称 | 需要确认 | 功能说明 |
-|---------|---------|---------|
-| `get_time` | ❌ | 获取当前系统时间 |
-| `list_dir` | ❌ | 列出目录下的文件和子目录 |
-| `project_tree` | ❌ | 获取项目目录结构（类似 tree 命令） |
-| `get_path` | ❌ | 获取文件/文件夹的绝对路径 |
-| `read_code` | ❌ | 按字符范围读取文件内容片段 |
-| `read_code_by_line` | ❌ | 按行读取代码片段（带行号） |
-| `search_in_files` | ❌ | 在项目中按正则搜索文本（自动忽略 `.git`/`.venv` 等） |
-| `delay` | ❌ | 延时函数 |
-| `make_dir` | ✅ | 创建目录（自动创建父目录） |
-| `write_code` | ✅ | 写入文件内容（覆盖，自动创建父目录） |
-| `append_code` | ✅ | 追加写入文件内容（自动创建父目录） |
-| `delete_path` | ✅ | 删除文件或目录（`recursive=True` 可递归） |
-| `replace_code_by_lines` | ✅ | 按行范围替换代码块 |
-| `terminal` | ✅ | 在终端运行指令（带超时） |
-| `run_python` | ✅ | 执行一小段 Python 代码 |
-| `shot_down_system` | ✅ | 关机 |
-
-> `需要确认` 的工具在执行时会触发 `on_tool_confirmation` 事件，适合接入人工审批流程。
->
-> 由于系统工具包使用了命名空间，工具在模型侧的实际名称为 `tina_sys_tools_{名称}`，例如 `tina_sys_tools_read_code`。
-
-### 6.2 后台工作器 `AgentWorker`
+### 6.1 后台工作器 `AgentWorker`
 
 `AgentWorker` 将 Agent 包装为异步后台服务，通过消息队列接收外部指令并持续处理：
 
@@ -986,7 +942,7 @@ asyncio.run(main())
 
 `AgentWorker` 还会将自身的 `put` 方法自动注册为 Agent 的工具，方便多 Agent 场景下互相调用。
 
-### 6.3 终端交互控制台 `run_agent_in_cli`
+### 6.2 终端交互控制台 `run_agent_in_cli`
 
 快速启动一个 Agent 交互式终端，适合调试和测试：
 
@@ -1012,7 +968,7 @@ run_agent_in_cli(agent)
 | `#clear` | 清屏 |
 | `exit` / `quit` | 退出对话（`#exit` 不支持，会被当作普通输入） |
 
-### 6.4 多模态消息构建器 `build_multimodal_message`
+### 6.3 多模态消息构建器 `build_multimodal_message`
 
 用于灵活构建包含多模态内容的消息：
 
@@ -1031,7 +987,13 @@ print(message)
 # {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image_url", ...}]}
 ```
 
-### 6.5 终端界面 TUI（可选扩展）
+---
+
+## 七、拓展包（可选）
+
+除核心之外的可选能力：有**随主包提供**的（编码工具），也有拆成**独立发行包**的（终端界面、多 Agent 环境），按需安装、可独立更新与发布。主包内不再包含后者的实现（仅保留 `tina.utils.*` 兼容转发壳）。
+
+### 7.1 终端界面 TUI（`tina-tui`）
 
 终端界面由配套包 **`tina-tui`**（基于 [Textual](https://textual.textualize.io/)）提供，作为**可选扩展**单独发行：方便你测试自己写的 Agent，也可以直接当作自己的 TUI 来用。核心不依赖它，需要额外安装：
 
@@ -1039,6 +1001,21 @@ print(message)
 pip install tina-python[tui]   # 等价于安装 tina-tui
 ```
 
+**开箱即用的 `tinacode` 命令**：装好后可以在任意目录直接起一个编码 agent，不用写 Python：
+
+```bash
+cd <你的项目>
+tinacode
+```
+
+- 工作目录 = 你敲命令时所在的目录（`code_*` 工具的相对路径以它为准）
+- 会话历史存到 `<cwd>/.tina/chat_sessions/`，**按目录隔离**
+- 模型配置读 `<cwd>/tina.env` 或 `.env`，没有则回退全局 `~/.tina/tina.env`
+- 目录里的 `.tinacode.md` / `AGENTS.md` / `.tina.md` 自动注入系统提示（目录级定制不用改代码）
+- 工具集是 `CodingTools`（见 [7.3](#73-编码工具codingtools)）
+
+自己组装 Agent 再交给 TUI：
+
 ```python
 from tina import Agent, Tools
 from tina.llm import BaseAPI
@@ -1059,8 +1036,9 @@ run_agent_in_tui(agent, max_tokens=32000)
 - 自动为 Agent 注册工具确认事件（`require_confirmation=True` 的工具会弹出选择条）
 - 上下文 token 占用与上限进度（显示百分比，≥80% 变黄、超限变红警告），运行时显示动画
 - `Esc` 可打断本轮回复；已生成的部分正文写回上下文，进行中的工具调用记为「该次调用被打断」
-- 输入框支持多行与粘贴；`Enter` 发送、`Shift+Enter` 换行、`Tab` 补全命令
+- 输入框支持多行与粘贴；`Enter` 发送、`Shift+Enter` 换行、`Tab` 补全命令与会话 id
 - 底部粘性滚动：在底部时自动跟随输出，向上滚动查看历史时不会被打扰，滚回底部自动恢复
+- 会话自动归档到 `<项目>/.tina/chat_sessions/`：可切换 / 重命名 / 删除，首轮结束后自动起名
 - 可选 `unlimited_context=True`：用 tina 提供的无限制上下文管理器替换 Agent 的（不裁剪历史、不截断工具结果）
 
 | 指令 | 功能 |
@@ -1070,6 +1048,11 @@ run_agent_in_tui(agent, max_tokens=32000)
 | `#context` | 查看当前上下文 |
 | `#model` | 查看当前模型信息 |
 | `#tokens` | 查看当前上下文 token 占用 |
+| `#sessions` | 列出已保存的会话（可跟关键字过滤） |
+| `#switch` | 切换会话（按 id / id 前缀 / 标题） |
+| `#new` | 新建会话（当前会话自动保存） |
+| `#rename` | 重命名当前会话 |
+| `#delete` | 删除会话 |
 | `#compact` | 压缩上下文（让 Agent 自我总结并并入 system） |
 | `#clear` | 清空上下文与界面 |
 | `#exit` | 退出 |
@@ -1080,6 +1063,71 @@ run_agent_in_tui(agent, max_tokens=32000)
 
 完整说明（安装、指令、快捷键、自建界面）见 [`docs/tui.md`](./docs/tui.md)。
 
+### 7.2 多 Agent 环境（`tina-multi-agent`）
+
+多 Agent 场景由独立发行包 **`tina-multi-agent`** 提供：把多个各自独立的 `Agent`（含 `MultimodalAgent`）注册进一个「环境」，通过消息总线互相通信，并带一个 Web 调试控制台用于观测与介入。
+
+```bash
+pip install tina-python[multi-agent]   # 等价于安装 tina-multi-agent
+```
+
+```python
+from tina import Agent
+from tina.llm import BaseAPI
+from tina_multi_agent import MultiAgentEnvironment, MultiAgentWeb
+
+llm = BaseAPI()
+
+env = MultiAgentEnvironment(name="room")
+env.add_agent(Agent(llm=llm, name="alice", system_prompt="你是 alice"))
+env.add_agent(Agent(llm=llm, name="bob", system_prompt="你是 bob"))
+
+# 带 Web 控制台启动（自动启动环境）：打开 http://127.0.0.1:7077
+MultiAgentWeb(env, port=7077).run()
+```
+
+- 每个 Agent 一个收信队列；外部指令走 `add_user_message`，同伴消息作为带 `name` 的 assistant 消息注入。
+- 支持**回合中途注入**（`before_llm_call`）、打断（`env.interrupt`）、工具确认与权限表。
+- Web 控制台能力、消息总线、`POST /instruction`、`WS /ws` 事件等完整说明见 [`packages/tina-multi-agent/README.md`](./packages/tina-multi-agent/README.md)。
+
+> 兼容提示：旧路径 `tina.utils.multi_agent` 仍可用（主包内保留转发壳）；未安装 `tina-multi-agent` 时会提示安装。
+
+### 7.3 编码工具（`CodingTools`）
+
+面向「写代码」的**主包内置**能力（命名空间 `code`），像普通工具包一样按需搭配到任意 Agent：一个编码工具包 + 一个项目感知的上下文管理器。提供可靠的**局部编辑**（精确文本匹配 + 唯一性校验 + 原子写）、搜索增强与命令输出截断。
+
+```python
+from tina import Agent
+from tina.utils.coding_tools import CodingTools
+
+tools = CodingTools(root=".").get_tools()   # code_read / code_glob / code_grep / code_write / code_edit / code_patch / code_bash
+agent = Agent(llm=llm, tools=tools)
+```
+
+| 工具 | 说明 | 需确认 |
+|------|------|--------|
+| `code_read` | 按行读取（offset/limit、行号、总行数与截断提示） | 否 |
+| `code_glob` | 按 glob 查找文件（如 `**/*.py`） | 否 |
+| `code_grep` | 正则搜索（`include` / 上下文行 / 忽略大小写） | 否 |
+| `code_write` | 整文件写入（`.py` 写前语法校验） | ✅ |
+| `code_edit` | 精确文本替换（命中多次需 `replace_all`，返回 diff） | ✅ |
+| `code_patch` | 应用 unified diff 补丁（一次多处/跨行改动，行号可偏差、上下文对不上则整体中止） | ✅ |
+| `code_bash` | 执行命令（首尾截断、带 exit code） | ✅ |
+
+配套的项目感知上下文管理器（自动注入 `AGENTS.md` / `.tinacode.md` / `.tina.md`、工作目录与目录结构摘要，可用 `refresh_project_context()` 刷新）：
+
+既可在构造时传入，也可之后替换：
+
+```python
+from tina import Agent
+from tina.utils.coding_context import CodingContextManager
+
+agent = Agent(llm=llm, tools=tools, context_manager=CodingContextManager(root="."))
+# 或：agent.set_context_manager(CodingContextManager(root="."))
+```
+
+> 未显式传 `system_prompt` 时，Agent 会**保留** `context_manager` 自带的系统提示（不再用默认提示覆盖）；显式传 `system_prompt` 才会覆盖它。
+
 ---
 
 ## 附录
@@ -1090,7 +1138,7 @@ tina 支持通过环境文件配置 API 信息，自动从当前目录查找 `.e
 
 ```env
 LLM_API_KEY="your-api-key"
-BASE_URL="https://api.openai.com/v1/chat/completions"
+BASE_URL="https://api.openai.com/v1"
 MODEL_NAME="gpt-4o"
 MAX_INPUT=8000
 ```
@@ -1101,7 +1149,8 @@ MAX_INPUT=8000
 |------|------|
 | 核心功能 | `httpx`, `python-dotenv` |
 | MCP 支持 | `mcp` |
-| TUI 界面（可选） | `textual` |
+| TUI 界面（可选，`tina-tui`） | `textual` |
+| 多 Agent（可选，`tina-multi-agent`） | `fastapi`, `uvicorn`, `websockets` |
 | 测试 | `pytest`, `pytest-asyncio`, `pytest-cov` |
 
 ### 许可证

{tina_python-0.7.0 → tina_python-0.7.2}/README.md

@@ -15,10 +15,13 @@ pip install tina-python
 # 如果需要使用 MCP（模型上下文协议）服务
 pip install tina-python[mcp]
 
-# 如果需要 TUI 终端界面
+# 如果需要 TUI 终端界面（独立发行包 tina-tui）
 pip install tina-python[tui]
 
-# 一次装齐所有可选功能（TUI + MCP）
+# 如果需要多 Agent 环境 + Web 调试控制台（独立发行包 tina-multi-agent）
+pip install tina-python[multi-agent]
+
+# 一次装齐所有可选功能（TUI + 多 Agent + MCP）
 pip install tina-python[all]
 
 # 如果需要运行测试
@@ -34,7 +37,7 @@ from tina.llm import BaseAPI
 # 1. 实例化大模型（支持通过 tina.env 文件配置）
 llm = BaseAPI(
     api_key="your-api-key",
-    base_url="https://api.openai.com/v1/chat/completions",
+    base_url="https://api.openai.com/v1",
     model="gpt-4o"
 )
 
@@ -75,7 +78,7 @@ for chunk in result:
 - [四、MCP 支持 —— 模型上下文协议](#四mcp-支持--模型上下文协议)
 - [五、多模态支持](#五多模态支持)
 - [六、快速开发工具](#六快速开发工具)
-- [6.5 终端界面 TUI（可选扩展）](#65-终端界面-tui可选扩展)
+- [七、拓展包（可选）](#七拓展包可选)
 
 ---
 
@@ -103,7 +106,8 @@ tina 是一个轻量、模块化的 AI 智能体框架，专注于让开发者
 | **MCPClient** | MCP 集成 | 连接 MCP 服务器生态（stdio/SSE） |
 | **ContextManager** | 上下文管理 | 滚动窗口策略，自动截断 |
 | **AgentEvents** | 事件系统 | 贯穿 Agent 生命周期的回调钩子 |
-| **TUI（可选）** | 终端界面 | 测试你写的 Agent 的交互控制台，也可当作自己的 TUI 使用 |
+| **TUI（可选）** | 终端界面 | 独立包 `tina-tui`：测试 Agent 的交互控制台，也可当作自己的 TUI 使用 |
+| **多 Agent（可选）** | 多 Agent 环境 | 独立包 `tina-multi-agent`：消息总线 + Web 调试控制台 |
 
 ---
 
@@ -122,7 +126,7 @@ llm = BaseAPI()
 # 或者：手动传入参数
 llm = BaseAPI(
     api_key="your-api-key",
-    base_url="https://api.openai.com/v1/chat/completions",
+    base_url="https://api.openai.com/v1",
     model="gpt-4o"
 )
 ```
@@ -130,11 +134,11 @@ llm = BaseAPI(
 `tina.env` 文件示例：
 ```env
 LLM_API_KEY="your-api-key"
-BASE_URL="https://api.openai.com/v1/chat/completions"
+BASE_URL="https://api.openai.com/v1"
 MODEL_NAME="gpt-4o"
 ```
 
-> **注意**：`base_url` 需要包含完整的 `/chat/completions` 路由，tina 不会自动补充。
+> **base_url 规则（0.7.0 起）**：只写服务根地址即可（如 `https://api.openai.com/v1`），tina 会自动补上 `/chat/completions`；写完整地址（`.../chat/completions`）也依然兼容。旧文档要求"必须自带 `/chat/completions`"的说法已作废。
 
 ### 1.2 非流式调用
 
@@ -669,7 +673,7 @@ tina 支持通过 MCP（Model Context Protocol）连接外部工具生态。
 pip install tina-python[mcp]
 ```
 
-> 想一次装齐所有可选功能（TUI + MCP）：`pip install tina-python[all]`
+> 想一次装齐所有可选功能（TUI + 多 Agent + MCP）：`pip install tina-python[all]`
 
 ### 4.2 使用 MCP 客户端
 
@@ -860,55 +864,7 @@ message = build_multimodal_message(
 
 tina 提供了一些开箱即用的工具函数和工具包，帮助你快速搭建应用。
 
-### 6.1 系统工具包 `system_tools`
-
-tina 自带一套系统工具包，包含文件操作、代码执行等常用功能：
-
-```python
-from tina import Agent, Tools
-from tina.llm import BaseAPI
-from tina.utils.system_tools import system_tools
-
-tools = Tools(name="my_tools")
-tools += system_tools  # 添加 tina 自带的系统工具包（工具集需命名）
-
-agent = Agent(
-    llm=BaseAPI(),
-    tools=tools,
-    system_prompt="你是一个系统助手，可以帮助我管理文件和执行代码"
-)
-
-result = agent.predict(instruction="帮我看看当前目录下有哪些文件", stream=True)
-for chunk in result:
-    print(chunk.content, end="")
-```
-
-**内置工具一览：**
-
-| 工具名称 | 需要确认 | 功能说明 |
-|---------|---------|---------|
-| `get_time` | ❌ | 获取当前系统时间 |
-| `list_dir` | ❌ | 列出目录下的文件和子目录 |
-| `project_tree` | ❌ | 获取项目目录结构（类似 tree 命令） |
-| `get_path` | ❌ | 获取文件/文件夹的绝对路径 |
-| `read_code` | ❌ | 按字符范围读取文件内容片段 |
-| `read_code_by_line` | ❌ | 按行读取代码片段（带行号） |
-| `search_in_files` | ❌ | 在项目中按正则搜索文本（自动忽略 `.git`/`.venv` 等） |
-| `delay` | ❌ | 延时函数 |
-| `make_dir` | ✅ | 创建目录（自动创建父目录） |
-| `write_code` | ✅ | 写入文件内容（覆盖，自动创建父目录） |
-| `append_code` | ✅ | 追加写入文件内容（自动创建父目录） |
-| `delete_path` | ✅ | 删除文件或目录（`recursive=True` 可递归） |
-| `replace_code_by_lines` | ✅ | 按行范围替换代码块 |
-| `terminal` | ✅ | 在终端运行指令（带超时） |
-| `run_python` | ✅ | 执行一小段 Python 代码 |
-| `shot_down_system` | ✅ | 关机 |
-
-> `需要确认` 的工具在执行时会触发 `on_tool_confirmation` 事件，适合接入人工审批流程。
->
-> 由于系统工具包使用了命名空间，工具在模型侧的实际名称为 `tina_sys_tools_{名称}`，例如 `tina_sys_tools_read_code`。
-
-### 6.2 后台工作器 `AgentWorker`
+### 6.1 后台工作器 `AgentWorker`
 
 `AgentWorker` 将 Agent 包装为异步后台服务，通过消息队列接收外部指令并持续处理：
 
@@ -948,7 +904,7 @@ asyncio.run(main())
 
 `AgentWorker` 还会将自身的 `put` 方法自动注册为 Agent 的工具，方便多 Agent 场景下互相调用。
 
-### 6.3 终端交互控制台 `run_agent_in_cli`
+### 6.2 终端交互控制台 `run_agent_in_cli`
 
 快速启动一个 Agent 交互式终端，适合调试和测试：
 
@@ -974,7 +930,7 @@ run_agent_in_cli(agent)
 | `#clear` | 清屏 |
 | `exit` / `quit` | 退出对话（`#exit` 不支持，会被当作普通输入） |
 
-### 6.4 多模态消息构建器 `build_multimodal_message`
+### 6.3 多模态消息构建器 `build_multimodal_message`
 
 用于灵活构建包含多模态内容的消息：
 
@@ -993,7 +949,13 @@ print(message)
 # {"role": "user", "content": [{"type": "text", "text": "..."}, {"type": "image_url", ...}]}
 ```
 
-### 6.5 终端界面 TUI（可选扩展）
+---
+
+## 七、拓展包（可选）
+
+除核心之外的可选能力：有**随主包提供**的（编码工具），也有拆成**独立发行包**的（终端界面、多 Agent 环境），按需安装、可独立更新与发布。主包内不再包含后者的实现（仅保留 `tina.utils.*` 兼容转发壳）。
+
+### 7.1 终端界面 TUI（`tina-tui`）
 
 终端界面由配套包 **`tina-tui`**（基于 [Textual](https://textual.textualize.io/)）提供，作为**可选扩展**单独发行：方便你测试自己写的 Agent，也可以直接当作自己的 TUI 来用。核心不依赖它，需要额外安装：
 
@@ -1001,6 +963,21 @@ print(message)
 pip install tina-python[tui]   # 等价于安装 tina-tui
 ```
 
+**开箱即用的 `tinacode` 命令**：装好后可以在任意目录直接起一个编码 agent，不用写 Python：
+
+```bash
+cd <你的项目>
+tinacode
+```
+
+- 工作目录 = 你敲命令时所在的目录（`code_*` 工具的相对路径以它为准）
+- 会话历史存到 `<cwd>/.tina/chat_sessions/`，**按目录隔离**
+- 模型配置读 `<cwd>/tina.env` 或 `.env`，没有则回退全局 `~/.tina/tina.env`
+- 目录里的 `.tinacode.md` / `AGENTS.md` / `.tina.md` 自动注入系统提示（目录级定制不用改代码）
+- 工具集是 `CodingTools`（见 [7.3](#73-编码工具codingtools)）
+
+自己组装 Agent 再交给 TUI：
+
 ```python
 from tina import Agent, Tools
 from tina.llm import BaseAPI
@@ -1021,8 +998,9 @@ run_agent_in_tui(agent, max_tokens=32000)
 - 自动为 Agent 注册工具确认事件（`require_confirmation=True` 的工具会弹出选择条）
 - 上下文 token 占用与上限进度（显示百分比，≥80% 变黄、超限变红警告），运行时显示动画
 - `Esc` 可打断本轮回复；已生成的部分正文写回上下文，进行中的工具调用记为「该次调用被打断」
-- 输入框支持多行与粘贴；`Enter` 发送、`Shift+Enter` 换行、`Tab` 补全命令
+- 输入框支持多行与粘贴；`Enter` 发送、`Shift+Enter` 换行、`Tab` 补全命令与会话 id
 - 底部粘性滚动：在底部时自动跟随输出，向上滚动查看历史时不会被打扰，滚回底部自动恢复
+- 会话自动归档到 `<项目>/.tina/chat_sessions/`：可切换 / 重命名 / 删除，首轮结束后自动起名
 - 可选 `unlimited_context=True`：用 tina 提供的无限制上下文管理器替换 Agent 的（不裁剪历史、不截断工具结果）
 
 | 指令 | 功能 |
@@ -1032,6 +1010,11 @@ run_agent_in_tui(agent, max_tokens=32000)
 | `#context` | 查看当前上下文 |
 | `#model` | 查看当前模型信息 |
 | `#tokens` | 查看当前上下文 token 占用 |
+| `#sessions` | 列出已保存的会话（可跟关键字过滤） |
+| `#switch` | 切换会话（按 id / id 前缀 / 标题） |
+| `#new` | 新建会话（当前会话自动保存） |
+| `#rename` | 重命名当前会话 |
+| `#delete` | 删除会话 |
 | `#compact` | 压缩上下文（让 Agent 自我总结并并入 system） |
 | `#clear` | 清空上下文与界面 |
 | `#exit` | 退出 |
@@ -1042,6 +1025,71 @@ run_agent_in_tui(agent, max_tokens=32000)
 
 完整说明（安装、指令、快捷键、自建界面）见 [`docs/tui.md`](./docs/tui.md)。
 
+### 7.2 多 Agent 环境（`tina-multi-agent`）
+
+多 Agent 场景由独立发行包 **`tina-multi-agent`** 提供：把多个各自独立的 `Agent`（含 `MultimodalAgent`）注册进一个「环境」，通过消息总线互相通信，并带一个 Web 调试控制台用于观测与介入。
+
+```bash
+pip install tina-python[multi-agent]   # 等价于安装 tina-multi-agent
+```
+
+```python
+from tina import Agent
+from tina.llm import BaseAPI
+from tina_multi_agent import MultiAgentEnvironment, MultiAgentWeb
+
+llm = BaseAPI()
+
+env = MultiAgentEnvironment(name="room")
+env.add_agent(Agent(llm=llm, name="alice", system_prompt="你是 alice"))
+env.add_agent(Agent(llm=llm, name="bob", system_prompt="你是 bob"))
+
+# 带 Web 控制台启动（自动启动环境）：打开 http://127.0.0.1:7077
+MultiAgentWeb(env, port=7077).run()
+```
+
+- 每个 Agent 一个收信队列；外部指令走 `add_user_message`，同伴消息作为带 `name` 的 assistant 消息注入。
+- 支持**回合中途注入**（`before_llm_call`）、打断（`env.interrupt`）、工具确认与权限表。
+- Web 控制台能力、消息总线、`POST /instruction`、`WS /ws` 事件等完整说明见 [`packages/tina-multi-agent/README.md`](./packages/tina-multi-agent/README.md)。
+
+> 兼容提示：旧路径 `tina.utils.multi_agent` 仍可用（主包内保留转发壳）；未安装 `tina-multi-agent` 时会提示安装。
+
+### 7.3 编码工具（`CodingTools`）
+
+面向「写代码」的**主包内置**能力（命名空间 `code`），像普通工具包一样按需搭配到任意 Agent：一个编码工具包 + 一个项目感知的上下文管理器。提供可靠的**局部编辑**（精确文本匹配 + 唯一性校验 + 原子写）、搜索增强与命令输出截断。
+
+```python
+from tina import Agent
+from tina.utils.coding_tools import CodingTools
+
+tools = CodingTools(root=".").get_tools()   # code_read / code_glob / code_grep / code_write / code_edit / code_patch / code_bash
+agent = Agent(llm=llm, tools=tools)
+```
+
+| 工具 | 说明 | 需确认 |
+|------|------|--------|
+| `code_read` | 按行读取（offset/limit、行号、总行数与截断提示） | 否 |
+| `code_glob` | 按 glob 查找文件（如 `**/*.py`） | 否 |
+| `code_grep` | 正则搜索（`include` / 上下文行 / 忽略大小写） | 否 |
+| `code_write` | 整文件写入（`.py` 写前语法校验） | ✅ |
+| `code_edit` | 精确文本替换（命中多次需 `replace_all`，返回 diff） | ✅ |
+| `code_patch` | 应用 unified diff 补丁（一次多处/跨行改动，行号可偏差、上下文对不上则整体中止） | ✅ |
+| `code_bash` | 执行命令（首尾截断、带 exit code） | ✅ |
+
+配套的项目感知上下文管理器（自动注入 `AGENTS.md` / `.tinacode.md` / `.tina.md`、工作目录与目录结构摘要，可用 `refresh_project_context()` 刷新）：
+
+既可在构造时传入，也可之后替换：
+
+```python
+from tina import Agent
+from tina.utils.coding_context import CodingContextManager
+
+agent = Agent(llm=llm, tools=tools, context_manager=CodingContextManager(root="."))
+# 或：agent.set_context_manager(CodingContextManager(root="."))
+```
+
+> 未显式传 `system_prompt` 时，Agent 会**保留** `context_manager` 自带的系统提示（不再用默认提示覆盖）；显式传 `system_prompt` 才会覆盖它。
+
 ---
 
 ## 附录
@@ -1052,7 +1100,7 @@ tina 支持通过环境文件配置 API 信息，自动从当前目录查找 `.e
 
 ```env
 LLM_API_KEY="your-api-key"
-BASE_URL="https://api.openai.com/v1/chat/completions"
+BASE_URL="https://api.openai.com/v1"
 MODEL_NAME="gpt-4o"
 MAX_INPUT=8000
 ```
@@ -1063,7 +1111,8 @@ MAX_INPUT=8000
 |------|------|
 | 核心功能 | `httpx`, `python-dotenv` |
 | MCP 支持 | `mcp` |
-| TUI 界面（可选） | `textual` |
+| TUI 界面（可选，`tina-tui`） | `textual` |
+| 多 Agent（可选，`tina-multi-agent`） | `fastapi`, `uvicorn`, `websockets` |
 | 测试 | `pytest`, `pytest-asyncio`, `pytest-cov` |
 
 ### 许可证

{tina_python-0.7.0 → tina_python-0.7.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "tina-python"
-version = "0.7.0"
+version = "0.7.2"
 description = "tina is in your computer!"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.10"
@@ -29,7 +29,9 @@ GitHub = "https://github.com/XIMOCY/tina.git"
 
 [project.optional-dependencies]
 tui = [
-    "tina-tui>=0.1.0",
+    # 0.2.0 起提供 tinacode 命令；不收紧的话，已装 tina-tui 0.1.0 的环境
+    # pip 不会升级它，用户拿不到 tinacode
+    "tina-tui>=0.2.0",
 ]
 multi-agent = [
     "tina-multi-agent>=0.1.0",
@@ -43,7 +45,7 @@ test = [
     "pytest-cov>=7.0",
 ]
 all = [
-    "tina-tui>=0.1.0",
+    "tina-tui>=0.2.0",
     "tina-multi-agent>=0.1.0",
     "mcp>=2.0",
 ]

{tina_python-0.7.0 → tina_python-0.7.2}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="tina-python",
-    version="0.7.0",
+    version="0.7.1",
     packages=find_packages(),
     package_data={"tina": ["py.typed"]},
     install_requires=["httpx", "python-dotenv"],

{tina_python-0.7.0 → tina_python-0.7.2}/tina/__init__.py

@@ -21,4 +21,4 @@ __all__ = [
     "AgentEvents",
     "FilesAPI",
 ]
-__version__ = "0.7.0"
+__version__ = "0.7.2"