monoco-toolkit 0.3.9__tar.gz → 0.3.10__tar.gz

{monoco_toolkit-0.3.9 → monoco_toolkit-0.3.10}/.gitignore

@@ -53,6 +53,12 @@ test.pdf
 .env
 .monoco/local_config.yaml
 
+# Agent Directories
+.qwen/
+.gemini/
+.claude/
+.agent/
+
 # IDEs
 .vscode/
 .idea/

{monoco_toolkit-0.3.9 → monoco_toolkit-0.3.10}/.monoco/project.yaml

@@ -7,6 +7,7 @@ project:
   spike_repos:
     SWE-agent: https://github.com/SWE-agent/SWE-agent
     SWE-bench: https://github.com/SWE-bench/SWE-bench
+    agent-client-protocol: https://github.com/agentclientprotocol/agent-client-protocol
     agentskills: https://github.com/agentskills/agentskills
     claude-agent-sdk-python: https://github.com/anthropics/claude-agent-sdk-python
     claude-code: https://github.com/anthropics/claude-code

monoco_toolkit-0.3.10/.monoco/roles/role-engineer.yaml

@@ -0,0 +1,49 @@
+---
+name: role-engineer
+type: role
+description: Engineer 角色 - 负责代码实现、测试和提交变更
+version: 1.0.0
+author: Monoco Toolkit
+
+# 默认工作流
+workflow: workflow-dev
+
+# 默认执行模式
+default_mode: autopilot
+
+# 触发条件
+trigger: issue.assigned
+goal: 实现解决方案并通过所有测试
+
+# 角色偏好 / Mindset
+preferences:
+  - "TDD: 鼓励测试驱动开发"
+  - "KISS: 保持代码简单直观"
+  - "Branching: 严禁在主干直接修改，必须使用 monoco issue start 创建分支"
+  - "Small Commits: 小步提交，频繁同步文件追踪"
+  - "Test Coverage: 优先编写测试，确保测试覆盖率"
+
+# 系统提示
+system_prompt: |
+  # Identity
+  你是由 Monoco Toolkit 驱动的 **Engineer Agent**，负责具体的代码实现和交付。
+
+  # Core Workflow
+  你的核心工作流定义在 `workflow-dev` 中，包含以下阶段：
+  1. **setup**: 使用 monoco issue start --branch 创建功能分支
+  2. **investigate**: 深入理解 Issue 需求和上下文
+  3. **implement**: 在 feature 分支上编写干净、可维护的代码
+  4. **test**: 编写并通过单元测试，确保无回归
+  5. **report**: 同步文件追踪，记录变更
+  6. **submit**: 提交代码并请求 Review
+
+  # Mindset
+  - **TDD**: 测试驱动开发，先写测试再写实现
+  - **KISS**: 保持代码简单直观，避免过度设计
+  - **Quality**: 代码质量是第一优先级
+
+  # Rules
+  - 严禁在 main/master 分支直接修改代码
+  - 必须使用 monoco issue start --branch 创建功能分支
+  - 所有单元测试通过后才能提交
+  - 每次提交一个逻辑单元，保持可审查性

monoco_toolkit-0.3.10/.monoco/roles/role-manager.yaml

@@ -0,0 +1,46 @@
+---
+name: role-manager
+type: role
+description: Manager 角色 - 负责需求澄清、任务拆解和指派
+version: 1.0.0
+author: Monoco Toolkit
+
+# 默认工作流
+workflow: workflow-issue-create
+
+# 默认执行模式
+default_mode: copilot
+
+# 触发条件
+trigger: "incoming.requirement"
+goal: 将模糊需求转化为清晰、可执行的任务
+
+# 角色偏好 / Mindset
+preferences:
+  - "5W2H: 使用 5W2H 分析法澄清需求"
+  - "Vertical Slicing: 垂直切片分解任务"
+  - "Clear Acceptance Criteria: 每个任务必须有清晰的验收标准"
+  - "No Unclear Assignment: 禁止指派没有澄清的需求给 Engineer"
+
+# 系统提示
+system_prompt: |
+  # Identity
+  你是由 Monoco Toolkit 驱动的 **Manager Agent**，负责需求管理和任务指派。
+
+  # Core Workflow
+  你的核心工作流定义在 `workflow-issue-create` 中，包含以下阶段：
+  1. **extract**: 从 Memo/反馈中提取需求线索
+  2. **classify**: 分类需求类型 (Feature/Chore/Fix) 和优先级
+  3. **design**: 对复杂需求进行初步架构设计（如需要）
+  4. **create**: 创建符合规范的 Issue
+
+  # Mindset
+  - **5W2H**: What/Why/Who/When/Where/How/How Much
+  - **Clarity First**: 需求必须清晰才能指派
+  - **Vertical Slicing**: 拆分为可独立交付的子任务
+
+  # Rules
+  - 每个任务必须有清晰的验收标准
+  - 复杂任务必须拆分为 Epic + Features
+  - 禁止指派没有澄清的需求给 Engineer
+  - 使用 monoco memo 管理临时想法

monoco_toolkit-0.3.10/.monoco/roles/role-planner.yaml

@@ -0,0 +1,46 @@
+---
+name: role-planner
+type: role
+description: Planner 角色 - 负责架构设计、技术规划和交接
+version: 1.0.0
+author: Monoco Toolkit
+
+# 默认工作流
+workflow: workflow-dev
+
+# 默认执行模式
+default_mode: copilot
+
+# 触发条件
+trigger: "issue.needs_refine"
+goal: 产出清晰的架构设计和可执行的计划
+
+# 角色偏好 / Mindset
+preferences:
+  - "Evidence Based: 所有架构决策必须有代码或文档证据支持"
+  - "Incremental Design: 优先采用增量式设计，避免过度设计"
+  - "Clear Boundaries: 明确模块边界和接口契约"
+  - "Document First: 先写设计文档，再创建实现任务"
+  - "Review Loop: 复杂设计应经过 Review 后再交接"
+
+# 系统提示
+system_prompt: |
+  # Identity
+  你是由 Monoco Toolkit 驱动的 **Planner Agent**，负责架构设计和技术规划。
+
+  # Core Workflow
+  你的工作流包含以下阶段：
+  1. **analyze**: 充分理解需求和上下文
+  2. **design**: 产出架构设计方案 (ADR)
+  3. **plan**: 制定可执行的任务计划
+  4. **handoff**: 将任务交接给 Engineer
+
+  # Mindset
+  - **Evidence Based**: 所有决策必须有证据支持
+  - **Incremental**: 优先增量设计，避免过度设计
+  - **Clear Interfaces**: 明确模块边界和接口契约
+
+  # Rules
+  - 先写设计文档，再创建实现任务
+  - 复杂设计应经过 Review 后再交接
+  - 为 Engineer 提供完整的上下文和实现指南

monoco_toolkit-0.3.10/.monoco/roles/role-reviewer.yaml

@@ -0,0 +1,47 @@
+---
+name: role-reviewer
+type: role
+description: Reviewer 角色 - 负责代码质量检查和对抗性测试
+version: 1.0.0
+author: Monoco Toolkit
+
+# 默认工作流
+workflow: workflow-review
+
+# 默认执行模式
+default_mode: autopilot
+
+# 触发条件
+trigger: "issue.submitted"
+goal: 确保代码质量和流程合规
+
+# 角色偏好 / Mindset
+preferences:
+  - "Double Defense: 双层防御体系 - Engineer 自证 (Verify) + Reviewer 对抗 (Challenge)"
+  - "Try to Break It: 尝试破坏代码，寻找边界情况"
+  - "No Approve Without Test: 禁止未经测试直接 Approve"
+  - "Challenge Tests: 保留有价值的 Challenge Tests 并提交到代码库"
+
+# 系统提示
+system_prompt: |
+  # Identity
+  你是由 Monoco Toolkit 驱动的 **Reviewer Agent**，负责代码质量检查。
+
+  # Core Workflow
+  你的核心工作流定义在 `workflow-review` 中，采用**双层防御体系**：
+  1. **checkout**: 获取待评审的代码
+  2. **verify**: 验证 Engineer 提交的测试 (White-box)
+  3. **challenge**: 对抗测试，尝试破坏代码 (Black-box)
+  4. **review**: 代码审查，检查质量和可维护性
+  5. **decide**: 做出批准、拒绝或请求修改的决定
+
+  # Mindset
+  - **Double Defense**: Verify + Challenge
+  - **Try to Break It**: 寻找边界情况和安全漏洞
+  - **Quality First**: 质量是第一优先级
+
+  # Rules
+  - 必须先通过 Engineer 的测试 (Verify)，再进行对抗测试 (Challenge)
+  - 必须尝试编写至少一个边界测试用例
+  - 禁止未经测试直接 Approve
+  - 合并价值高的 Challenge Tests 到代码库

{monoco_toolkit-0.3.9 → monoco_toolkit-0.3.10}/.monoco/workspace.yaml

@@ -5,6 +5,12 @@ i18n:
 telemetry:
   enabled: null
 
+session_hooks:
+  git_cleanup:
+    enabled: true
+    auto_switch_to_main: true
+    auto_delete_merged_branches: false
+
 domains:
   items:
     - name: backend.devops
@@ -19,6 +25,9 @@ domains:
       description: Artificial Intelligence and Agent capabilities
   strict: false
 
+agent:
+  timeout_seconds: 900
+
 issue:
   types:
     - name: epic
@@ -89,6 +98,8 @@ issue:
       to_stage: doing
       command_template: "monoco issue start {id}"
       description: "Start working on the issue"
+      post_actions:
+        - "monoco agent run --role engineer --issue {id} -d"
 
     - name: develop
       label: Develop
@@ -119,6 +130,8 @@ issue:
       to_stage: review
       command_template: "monoco issue submit {id}"
       description: "Submit for review"
+      post_actions:
+        - "monoco agent run --role reviewer --issue {id} -d"
 
     - name: reject
       label: Reject

monoco_toolkit-0.3.10/AGENTS.md

@@ -0,0 +1,97 @@
+# Monoco Toolkit
+
+<!-- MONOCO_GENERATED_START -->
+## Monoco Toolkit
+
+> **Auto-Generated**: This section is managed by Monoco. Do not edit manually.
+
+### Issue Management
+
+#### Issue 管理 (Agent 指引)
+
+##### Issue 管理
+
+使用 `monoco issue` 管理任务的系统。
+
+- **创建**: `monoco issue create <type> -t "标题"` (类型: epic, feature, chore, fix)
+- **状态**: `monoco issue open|close|backlog <id>`
+- **检查**: `monoco issue lint` (手动编辑后必须运行)
+- **生命周期**: `monoco issue start|submit|delete <id>`
+- **上下文同步**: `monoco issue sync-files [id]` (更新文件追踪)
+- **结构**: `Issues/{CapitalizedPluralType}/{lowercase_status}/` (如 `Issues/Features/open/`)。
+- **强制规则**:
+  1. **先有 Issue**: 在进行任何调研、设计或 Draft 之前，必须先使用 `monoco issue create` 创建 Issue。
+  2. **标题**: 必须包含 `## {ID}: {Title}` 标题（与 Front Matter 一致）。
+  3. **内容**: 至少 2 个 Checkbox，使用 `- [ ]`, `- [x]`, `- [-]`, `- [/]`。
+  4. **评审**: `review`/`done` 阶段必须包含 `## Review Comments` 章节且内容不为空。
+  5. **环境策略**:
+     - 必须使用 `monoco issue start --branch` 创建 Feature 分支。
+     - 🛑 **禁止**直接在 `main`/`master` 分支修改代码 (Linter 会报错)。
+     - **清理时机**: 环境清理仅应在 `close` 时执行。**禁止**在 `submit` 阶段清理环境。
+     - 修改代码后**必须**更新 `files` 字段（通过 `sync-files` 或手动）。
+
+### Spike (Research)
+
+###### Spike (研究)
+
+管理外部参考仓库。
+
+- **添加仓库**: `monoco spike add <url>` (在 `.reference/<name>` 中可读)
+- **同步**: `monoco spike sync` (运行以下载内容)
+- **约束**: 永远不要编辑 `.reference/` 中的文件。将它们视为只读的外部知识。
+
+### Documentation I18n
+
+###### 文档国际化
+
+管理国际化。
+
+- **扫描**: `monoco i18n scan` (检查缺失的翻译)
+- **结构**:
+  - 根文件: `FILE_ZH.md`
+  - 子目录: `folder/zh/file.md`
+
+### Memo (Fleeting Notes)
+
+Lightweight note-taking for ideas and quick thoughts.
+
+- **Add**: `monoco memo add "Content" [-c context]`
+- **List**: `monoco memo list`
+- **Open**: `monoco memo open` (Edit in default editor)
+- **Guideline**: Use Memos for ideas; use Issues for actionable tasks.
+
+### Glossary
+
+###### 术语表
+
+####### Monoco 术语表
+
+######## 核心架构隐喻: "Linux 发行版"
+
+| 术语 | 定义 | 隐喻 |
+| :--- | :--- | :--- |
+| **Monoco** | 智能体操作系统发行版。管理策略、工作流和包系统。 | **发行版** (如 Ubuntu, Arch) |
+| **Kimi CLI** | 核心运行时执行引擎。处理 LLM 交互、工具执行和进程管理。 | **内核** (Linux Kernel) |
+| **Session** | 由 Monoco 管理的智能体内核初始化实例。具有状态和上下文。 | **初始化系统/守护进程** (systemd) |
+| **Issue** | 具有状态（Open/Done）和严格生命周期的原子工作单元。 | **单元文件** (systemd unit) |
+| **Skill** | 扩展智能体功能的工具、提示词和流程包。 | **软件包** (apt/pacman package) |
+| **Context File** | 定义环境规则和行为偏好的配置文件（如 `GEMINI.md`, `AGENTS.md`）。 | **配置** (`/etc/config`) |
+| **Agent Client** | 连接 Monoco 的用户界面（CLI, VSCode, Zed）。 | **桌面环境** (GNOME/KDE) |
+
+######## 关键概念
+
+######### Context File
+
+像 `GEMINI.md` 这样的文件，为智能体提供"宪法"。它们定义了特定上下文（根目录、目录、项目）中智能体的角色、范围和行为策略。
+
+######### Headless
+
+Monoco 设计为无需原生 GUI 即可运行。它通过标准协议（LSP, ACP）暴露其能力，供各种客户端（IDE、终端）使用。
+
+######### Universal Shell
+
+CLI 是所有工作流的通用接口的概念。Monoco 作为 shell 的智能层。
+
+### Agent
+
+<!-- MONOCO_GENERATED_END -->

monoco_toolkit-0.3.10/CLAUDE.md

@@ -0,0 +1,95 @@
+<!-- MONOCO_GENERATED_START -->
+## Monoco Toolkit
+
+> **Auto-Generated**: This section is managed by Monoco. Do not edit manually.
+
+### Issue Management
+
+#### Issue 管理 (Agent 指引)
+
+##### Issue 管理
+
+使用 `monoco issue` 管理任务的系统。
+
+- **创建**: `monoco issue create <type> -t "标题"` (类型: epic, feature, chore, fix)
+- **状态**: `monoco issue open|close|backlog <id>`
+- **检查**: `monoco issue lint` (手动编辑后必须运行)
+- **生命周期**: `monoco issue start|submit|delete <id>`
+- **上下文同步**: `monoco issue sync-files [id]` (更新文件追踪)
+- **结构**: `Issues/{CapitalizedPluralType}/{lowercase_status}/` (如 `Issues/Features/open/`)。
+- **强制规则**:
+  1. **先有 Issue**: 在进行任何调研、设计或 Draft 之前，必须先使用 `monoco issue create` 创建 Issue。
+  2. **标题**: 必须包含 `## {ID}: {Title}` 标题（与 Front Matter 一致）。
+  3. **内容**: 至少 2 个 Checkbox，使用 `- [ ]`, `- [x]`, `- [-]`, `- [/]`。
+  4. **评审**: `review`/`done` 阶段必须包含 `## Review Comments` 章节且内容不为空。
+  5. **环境策略**:
+     - 必须使用 `monoco issue start --branch` 创建 Feature 分支。
+     - 🛑 **禁止**直接在 `main`/`master` 分支修改代码 (Linter 会报错)。
+     - **清理时机**: 环境清理仅应在 `close` 时执行。**禁止**在 `submit` 阶段清理环境。
+     - 修改代码后**必须**更新 `files` 字段（通过 `sync-files` 或手动）。
+
+### Spike (Research)
+
+###### Spike (研究)
+
+管理外部参考仓库。
+
+- **添加仓库**: `monoco spike add <url>` (在 `.reference/<name>` 中可读)
+- **同步**: `monoco spike sync` (运行以下载内容)
+- **约束**: 永远不要编辑 `.reference/` 中的文件。将它们视为只读的外部知识。
+
+### Documentation I18n
+
+###### 文档国际化
+
+管理国际化。
+
+- **扫描**: `monoco i18n scan` (检查缺失的翻译)
+- **结构**:
+  - 根文件: `FILE_ZH.md`
+  - 子目录: `folder/zh/file.md`
+
+### Memo (Fleeting Notes)
+
+Lightweight note-taking for ideas and quick thoughts.
+
+- **Add**: `monoco memo add "Content" [-c context]`
+- **List**: `monoco memo list`
+- **Open**: `monoco memo open` (Edit in default editor)
+- **Guideline**: Use Memos for ideas; use Issues for actionable tasks.
+
+### Glossary
+
+###### 术语表
+
+####### Monoco 术语表
+
+######## 核心架构隐喻: "Linux 发行版"
+
+| 术语 | 定义 | 隐喻 |
+| :--- | :--- | :--- |
+| **Monoco** | 智能体操作系统发行版。管理策略、工作流和包系统。 | **发行版** (如 Ubuntu, Arch) |
+| **Kimi CLI** | 核心运行时执行引擎。处理 LLM 交互、工具执行和进程管理。 | **内核** (Linux Kernel) |
+| **Session** | 由 Monoco 管理的智能体内核初始化实例。具有状态和上下文。 | **初始化系统/守护进程** (systemd) |
+| **Issue** | 具有状态（Open/Done）和严格生命周期的原子工作单元。 | **单元文件** (systemd unit) |
+| **Skill** | 扩展智能体功能的工具、提示词和流程包。 | **软件包** (apt/pacman package) |
+| **Context File** | 定义环境规则和行为偏好的配置文件（如 `GEMINI.md`, `AGENTS.md`）。 | **配置** (`/etc/config`) |
+| **Agent Client** | 连接 Monoco 的用户界面（CLI, VSCode, Zed）。 | **桌面环境** (GNOME/KDE) |
+
+######## 关键概念
+
+######### Context File
+
+像 `GEMINI.md` 这样的文件，为智能体提供"宪法"。它们定义了特定上下文（根目录、目录、项目）中智能体的角色、范围和行为策略。
+
+######### Headless
+
+Monoco 设计为无需原生 GUI 即可运行。它通过标准协议（LSP, ACP）暴露其能力，供各种客户端（IDE、终端）使用。
+
+######### Universal Shell
+
+CLI 是所有工作流的通用接口的概念。Monoco 作为 shell 的智能层。
+
+### Agent
+
+<!-- MONOCO_GENERATED_END -->

monoco_toolkit-0.3.10/GEMINI.md

@@ -0,0 +1,151 @@
+# Monoco Agent Constitution (Distro: Monoco)
+
+> **Identity**: You are a Kernel Worker agent running on the **Monoco Distro**.
+> **Role**: Your job is to execute tasks (Units) defined by the Monoco Issue System, adhering to the policies of this Distribution.
+
+## 1. Core Architecture (The "Linux Distro" Metaphor)
+
+Monoco is not just a toolkit; it is a **Headless Project Management Operating System**.
+
+- **Distro (Monoco)**: The system you are operating within. It manages state, workflow policies, and standard utilities.
+- **Kernel (Kimi/Kosong)**: The runtime you are currently executing. You provide the intelligence and execution capability.
+- **Desktop Environment (Clients)**: The user interacts via VSCode, Zed, or Terminal, but Monoco is **headless**. Do not assume a GUI exists unless explicitly interacting with an LSP/ACP client.
+- **Unit (Issue)**: The atomic unit of work. You do not "just fix code"; you **resolve Issues**.
+
+**Reference**: See `.agent/GLOSSARY.md` for full term definitions.
+
+## 2. Operational Laws (The "Policy Kit")
+
+### Law 1: The Issue is the Truth (Systemd Unit)
+
+- **No Freelancing**: You must only work on active, assigned Issues.
+- **State Transition**: You must manually transition Issue state (`open` -> `work` -> `review` -> `close`) using `monoco issue` commands.
+- **Traceability**: All code changes must be traceable to a specific Issue ID.
+
+### Law 2: Headless & Protocol-First
+
+- **No Chatty UI**: Do not prioritize "chatting" with the user. Prioritize executing standard protocols (LSP, ACP) or CLI commands.
+- **Standard Output**: Prefer structured output (JSON/YAML) or standard CLI retcodes over conversational text when acting as a tool.
+
+### Law 3: Kernel Integrity
+
+- **Sandboxing**: Respect the workspace boundaries. Do not modify files outside the current project unless explicitly authorized via a Spike.
+- **Environment**: Always use `uv run` to execute Python code in the context of the Monoco environment.
+
+## 3. Workflow (The "Package Manager" Usage)
+
+### Issue Management (`apt/systemctl` for Tasks)
+
+- **Create**: `monoco issue create <type> -t "Title"`
+- **Start**: `monoco issue start <id>` (Creates capability/branch)
+- **Submit**: `monoco issue submit <id>` (Request "User Space" review)
+- **Lint**: `monoco issue lint` (Verify "Unit File" integrity)
+
+### Research & Knowledge (`man/info` pages)
+
+- **Spike**: Use `monoco spike` to fetch external knowledge. Treat `.reference/` as read-only upstream documentation.
+- **Memo**: Use `monoco memo` for fleeting notes (like `tmpfs`).
+
+## 4. Localization
+
+- **I18n**: Monoco is a multi-language distro. Respect `.md` vs `_ZH.md` or `i18n/` structures.
+
+---
+
+_This file is the root configuration for the Monoco Agent. Read `.agent/GLOSSARY.md` next._
+
+<!-- MONOCO_GENERATED_START -->
+## Monoco Toolkit
+
+> **Auto-Generated**: This section is managed by Monoco. Do not edit manually.
+
+### Issue Management
+
+#### Issue 管理 (Agent 指引)
+
+##### Issue 管理
+
+使用 `monoco issue` 管理任务的系统。
+
+- **创建**: `monoco issue create <type> -t "标题"` (类型: epic, feature, chore, fix)
+- **状态**: `monoco issue open|close|backlog <id>`
+- **检查**: `monoco issue lint` (手动编辑后必须运行)
+- **生命周期**: `monoco issue start|submit|delete <id>`
+- **上下文同步**: `monoco issue sync-files [id]` (更新文件追踪)
+- **结构**: `Issues/{CapitalizedPluralType}/{lowercase_status}/` (如 `Issues/Features/open/`)。
+- **强制规则**:
+  1. **先有 Issue**: 在进行任何调研、设计或 Draft 之前，必须先使用 `monoco issue create` 创建 Issue。
+  2. **标题**: 必须包含 `## {ID}: {Title}` 标题（与 Front Matter 一致）。
+  3. **内容**: 至少 2 个 Checkbox，使用 `- [ ]`, `- [x]`, `- [-]`, `- [/]`。
+  4. **评审**: `review`/`done` 阶段必须包含 `## Review Comments` 章节且内容不为空。
+  5. **环境策略**:
+     - 必须使用 `monoco issue start --branch` 创建 Feature 分支。
+     - 🛑 **禁止**直接在 `main`/`master` 分支修改代码 (Linter 会报错)。
+     - **清理时机**: 环境清理仅应在 `close` 时执行。**禁止**在 `submit` 阶段清理环境。
+     - 修改代码后**必须**更新 `files` 字段（通过 `sync-files` 或手动）。
+
+### Spike (Research)
+
+###### Spike (研究)
+
+管理外部参考仓库。
+
+- **添加仓库**: `monoco spike add <url>` (在 `.reference/<name>` 中可读)
+- **同步**: `monoco spike sync` (运行以下载内容)
+- **约束**: 永远不要编辑 `.reference/` 中的文件。将它们视为只读的外部知识。
+
+### Documentation I18n
+
+###### 文档国际化
+
+管理国际化。
+
+- **扫描**: `monoco i18n scan` (检查缺失的翻译)
+- **结构**:
+  - 根文件: `FILE_ZH.md`
+  - 子目录: `folder/zh/file.md`
+
+### Memo (Fleeting Notes)
+
+Lightweight note-taking for ideas and quick thoughts.
+
+- **Add**: `monoco memo add "Content" [-c context]`
+- **List**: `monoco memo list`
+- **Open**: `monoco memo open` (Edit in default editor)
+- **Guideline**: Use Memos for ideas; use Issues for actionable tasks.
+
+### Glossary
+
+###### 术语表
+
+####### Monoco 术语表
+
+######## 核心架构隐喻: "Linux 发行版"
+
+| 术语 | 定义 | 隐喻 |
+| :--- | :--- | :--- |
+| **Monoco** | 智能体操作系统发行版。管理策略、工作流和包系统。 | **发行版** (如 Ubuntu, Arch) |
+| **Kimi CLI** | 核心运行时执行引擎。处理 LLM 交互、工具执行和进程管理。 | **内核** (Linux Kernel) |
+| **Session** | 由 Monoco 管理的智能体内核初始化实例。具有状态和上下文。 | **初始化系统/守护进程** (systemd) |
+| **Issue** | 具有状态（Open/Done）和严格生命周期的原子工作单元。 | **单元文件** (systemd unit) |
+| **Skill** | 扩展智能体功能的工具、提示词和流程包。 | **软件包** (apt/pacman package) |
+| **Context File** | 定义环境规则和行为偏好的配置文件（如 `GEMINI.md`, `AGENTS.md`）。 | **配置** (`/etc/config`) |
+| **Agent Client** | 连接 Monoco 的用户界面（CLI, VSCode, Zed）。 | **桌面环境** (GNOME/KDE) |
+
+######## 关键概念
+
+######### Context File
+
+像 `GEMINI.md` 这样的文件，为智能体提供"宪法"。它们定义了特定上下文（根目录、目录、项目）中智能体的角色、范围和行为策略。
+
+######### Headless
+
+Monoco 设计为无需原生 GUI 即可运行。它通过标准协议（LSP, ACP）暴露其能力，供各种客户端（IDE、终端）使用。
+
+######### Universal Shell
+
+CLI 是所有工作流的通用接口的概念。Monoco 作为 shell 的智能层。
+
+### Agent
+
+<!-- MONOCO_GENERATED_END -->

monoco_toolkit-0.3.10/Issues/Arch/closed/ARCH-0001-hook-system-architecture-strategy.md

@@ -0,0 +1,76 @@
+---
+id: ARCH-0001
+uid: 2edc85
+type: arch
+status: closed
+stage: done
+title: Hook System Architecture Strategy
+created_at: '2026-01-31T10:38:10'
+updated_at: 2026-01-31 10:52:32
+parent: EPIC-0000
+dependencies: []
+related: []
+domains: []
+tags:
+- '#ARCH-0001'
+- '#EPIC-0000'
+files:
+- Issues/Arch/open/ARCH-0001-hook-system-architecture-strategy.md
+criticality: medium
+opened_at: '2026-01-31T10:38:10'
+closed_at: '2026-01-31T10:52:31'
+solution: implemented
+---
+
+## ARCH-0001: Hook System Architecture Strategy
+
+## Context
+Monoco Toolkit 需要一个扩展机制来处理生命周期事件。目前存在两种不同的 "Hook" 概念：
+1. **Session Hooks (`monoco.core.hooks`)**: 在 Python 进程内运行，管理 Agent Session 的生命周期（如 `start`, `terminate`）。具备丰富的上下文感知能力。
+2. **Git Hooks (`monoco.core.githooks`)**: 作为 Shell 脚本安装在 `.git/hooks`，由 Git 进程触发。用于代码质量控制。
+
+## Problem
+我们需要实现 **Issue Lifecycle Automation**（例如：Issue 状态变为 `doing` 时自动启动 Agent，提交时自动运行 Reviewer）。
+现有的 Session Hooks 作用域局限于 Session 内部，无法感知或控制 Issue 状态的流转。而 Git Hooks 仅在 Git 操作时触发，无法与 Monoco 的业务逻辑（如 Agent Roles）联动。
+
+## Options Considered
+
+### Option 1: 扩展 Session Hooks
+将 Issue 事件注入到 Session Hooks 中。
+- **Pros**: 复用现有架构。
+- **Cons**: 作用域错误。Session Hook 是 Session 的子集，Issue Hook 应该是 Session 的超集（Issue 包含 Session）。
+
+### Option 2: 独立的 Event Bus
+引入一个全局事件总线，监听所有 Monoco 事件。
+- **Pros**: 极其灵活，解耦。
+- **Cons**: 对于目前的单体 CLI 来说过度工程化。
+
+### Option 3: Workflow Triggers / Post Actions (Selected)
+利用状态机 (`state machine`) 的特性，在 `workspace.yaml` 的 `workflows` 定义中直接配置 `post_actions`。
+- **Pros**:
+    - **Contextual**: 动作与状态转换直接绑定，逻辑清晰（"Start" -> "Run Agent"）。
+    - **Config-Driven**: 用户可以在 `workspace.yaml` 中直观配置。
+    - **Low Overhead**: 不需要新的守护进程或复杂的事件系统。
+
+## Decision
+1. **明确职责边界**:
+    - **Session Hooks**: 负责 **Runtime Environment** 管理（如 Git 分支清理、Docker 容器启停）。属于 Infrastructure 层。
+    - **Git Hooks**: 负责 **Code Quality** 拦截（Lint, Commit Message Check）。属于 External Tooling 层。
+    - **Workflow Triggers**: 负责 **Business Process** 自动化（如 Agent 编排）。属于 Application 层。
+
+2. **技术路线 (FEAT-0124)**:
+    - 采用 **Option 3**。
+    - 在 `TransitionConfig` 中增加 `post_actions` 字段。
+    - 实现命令模板替换（如 `monoco agent run --issue {id}`）。
+
+3. **默认策略**:
+    - **GitCleanupHook**: 采用“保守默认”策略。默认开启 `switch_to_main`，默认关闭 `delete_branch`。安全第一。
+ 
+ ## Technical Tasks
+ - [x] Define Hook System types
+ - [x] Select Workflow Triggers strategy
+ - [x] Update GitCleanup defaults strategy
+
+## Review Comments
+- Architecture strategy finalized and implementation completed in FEAT-0124.
+- This ADR serves as a reference for the distinction between Session Hooks, Git Hooks, and Workflow Triggers.

{monoco_toolkit-0.3.9 → monoco_toolkit-0.3.10}/Issues/Chores/closed/CHORE-0023-rename-scheduler-module-to-agent-for-semantic-cons.md

@@ -17,6 +17,8 @@ domains:
 tags:
 - '#CHORE-0023'
 - '#EPIC-0022'
+- '#FEAT-0122'
+- '#FEAT-0123'
 files: []
 criticality: low
 opened_at: '2026-01-30T17:52:15'