monoco-toolkit 0.3.12__tar.gz → 0.4.0__tar.gz

{monoco_toolkit-0.3.12 → monoco_toolkit-0.4.0}/.gitignore

@@ -64,6 +64,8 @@ test.pdf
 # IDEs
 .vscode/
 .idea/
+.cursor/
+.cursorrules
 *.swp
 *.swo
 .archives/

{monoco_toolkit-0.3.12 → monoco_toolkit-0.4.0}/.monoco/project.yaml

@@ -13,6 +13,7 @@ project:
     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
+    codex: https://github.com/openai/codex
     gemini-cli: https://github.com/google-gemini/gemini-cli
     kimi-agent-sdk: https://github.com/MoonshotAI/kimi-agent-sdk
     monoco-toolkit: https://github.com/IndenScale/monoco-toolkit

monoco_toolkit-0.4.0/AGENTS.md

@@ -0,0 +1,178 @@
+<!--
+⚠️ IMPORTANT: This file is partially managed by Monoco.
+- Content between MONOCO_GENERATED_START and MONOCO_GENERATED_END is auto-generated.
+- Do NOT manually edit the managed block.
+- Do NOT add content after MONOCO_GENERATED_END (use separate files instead).
+-->
+
+<!-- MONOCO_GENERATED_START -->
+## Monoco Toolkit
+
+> **Auto-Generated**: This section is managed by Monoco. Do not edit manually.
+
+### Agent
+
+###### Monoco 核心
+
+项目管理的核心工具包命令。
+
+- **初始化**: `monoco init` (初始化新的 Monoco 项目)
+- **配置**: `monoco config get|set <key> [value]` (管理配置)
+- **同步**: `monoco sync` (与 agent 环境同步)
+- **卸载**: `monoco uninstall` (清理 agent 集成)
+
+---
+
+##### ⚠️ Agent 必读: Git 工作流
+
+在修改任何代码前,**必须**遵循以下步骤:
+
+###### 标准流程
+
+1. **创建 Issue**: `monoco issue create feature -t "功能标题"`
+2. **🔒 启动隔离环境**: `monoco issue start FEAT-XXX --branch`
+   - ⚠️ **强制要求** `--branch` 参数
+   - ❌ 禁止在 `main`/`master` 分支直接修改代码
+3. **实现功能**: 正常编码和测试
+4. **同步文件**: `monoco issue sync-files` (提交前必须运行)
+5. **提交审查**: `monoco issue submit FEAT-XXX`
+6. **关闭 Issue**: `monoco issue close FEAT-XXX --solution implemented`
+
+###### 质量门禁
+
+- Git Hooks 会自动运行 `monoco issue lint` 和测试
+- 不要使用 `git commit --no-verify` 绕过检查
+- Linter 会阻止在受保护分支上的直接修改
+
+> 📖 详见 `monoco-issue` skill 获取完整工作流文档。
+
+### Issue Management
+
+#### Issue 管理
+
+使用 `monoco issue` 管理任务。
+
+- **创建**: `monoco issue create <type> -t "标题"`
+- **状态**: `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. **创建**: `monoco issue create feature -t "标题"`
+2. **启动**: `monoco issue start FEAT-XXX --branch`
+3. **实现**: 正常编码与测试。
+4. **同步**: `monoco issue sync-files` (更新 `files` 字段)。
+5. **提交**: `monoco issue submit FEAT-XXX`。
+6. **合规合并**: `monoco issue close FEAT-XXX --solution implemented` (合并到主线的唯一途径)。
+
+##### Git 合并策略
+
+- **禁止手动合并**: 严禁在 `main`/`master` 分支执行 `git merge` 或直接 `git pull`。
+- **原子合并**: `monoco issue close` 仅根据 Issue 的 `files` 列表合并变更。
+- **冲突处理**: 若产生冲突，请遵循 `close` 命令产生的指引进行手动 Cherry-Pick。
+- **清理策略**: `monoco issue close` 默认执行清理（删除分支/Worktree）。需保留请指定 `--no-prune`。
+
+### Memo (Fleeting Notes)
+
+轻量级笔记，用于快速记录想法。**信号队列模型** (FEAT-0165)。
+
+####### 信号队列语义
+
+- **Memo 是信号，不是资产** - 其价值在于触发行动
+- **文件存在 = 信号待处理** - Inbox 有未处理的 memo
+- **文件清空 = 信号已消费** - Memo 在处理后被删除
+- **Git 是档案** - 历史记录在 git 中，不在应用状态里
+
+####### 命令
+
+- **添加**: `monoco memo add "内容" [-c 上下文]` - 创建信号
+- **列表**: `monoco memo list` - 显示待处理信号（已消费的 memo 在 git 历史中）
+- **删除**: `monoco memo delete <id>` - 手动删除（通常自动消费）
+- **打开**: `monoco memo open` - 直接编辑 inbox
+
+####### 工作流
+
+1. 将想法捕获为 memo
+2. 当阈值（5个）达到时，自动触发 Architect
+3. Memo 被消费（删除）并嵌入 Architect 的 prompt
+4. Architect 从 memo 创建 Issue
+5. 不需要"链接"或"解决" memo - 消费后即消失
+
+####### 指南
+
+- 使用 Memo 记录** fleeting 想法** - 可能成为 Issue 的事情
+- 使用 Issue 进行**可操作的工作** - 结构化、可跟踪、有生命周期
+- 永远不要手动将 memo 链接到 Issue - 如果重要，创建一个 Issue
+
+### 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 的智能层。
+
+### Spike (Research)
+
+###### Spike (研究)
+
+管理外部参考仓库。
+
+- **添加仓库**: `monoco spike add <url>` (在 `.reference/<name>` 中可读)
+- **同步**: `monoco spike sync` (运行以下载内容)
+- **约束**: 永远不要编辑 `.reference/` 中的文件。将它们视为只读的外部知识。
+
+### Artifacts & Mailroom
+
+Monoco Artifacts 系统提供了多模态产物的生命周期管理能力，包括：
+
+1. **内容寻址存储 (CAS)**: 所有产物存储在全局池 `~/.monoco/artifacts` 中，基于内容的 SHA256 哈希值进行寻址和去重。
+2. **自动化摄取 (Mailroom)**: 通过监听 `.monoco/dropzone/` 目录，自动触发文档（Office, PDF 等）到 WebP 的转换流程。
+3. **环境追踪**: 自动探测系统中的 `LibreOffice`, `PyMuPDF` 等工具链。
+4. **元数据管理**: 项目本地维护 `manifest.jsonl`，记录所有产物的类型、哈希及创建时间。
+
+###### 常用操作建议
+
+- **上传文档**: 建议将原始文档放入 `.monoco/dropzone/`，等待 Mailroom 自动完成转换并注册为 Artifact。
+- **查看产物**: 检查 `.monoco/artifacts/manifest.jsonl` 获取当前可用的产物列表。
+- **引用产物**: 在多模态分析时，可以使用产物的 ID 或本地软链接路径。
+
+### Documentation I18n
+
+###### 文档国际化
+
+管理国际化。
+
+- **扫描**: `monoco i18n scan` (检查缺失的翻译)
+- **结构**:
+  - 根文件: `FILE_ZH.md`
+  - 子目录: `folder/zh/file.md`
+
+<!-- MONOCO_GENERATED_END -->

{monoco_toolkit-0.3.12 → monoco_toolkit-0.4.0}/Archaeology/REPORT_2026_01_26_01_30.md

@@ -11,8 +11,8 @@
 
 本次考古调查深入分析了 Monoco Toolkit 在 2026 年 1 月底的关键演进。调查发现，这段时间（特别是 1 月 30 日）标志着该项目从一个“任务管理工具”向“**Agent Native 操作系统**”的重大范式转移。
 
-*   **1月26日（维护期）**：重点在于稳固基础。团队发布了多个补丁版本 (0.3.4, 0.3.5)，优化了 Issue 生命周期管理（FEAT-0108），并增强了跨项目引用能力（FEAT-0107）。这一天的活动表现为典型的工程维护和渐进式改进。
-*   **1月30日（革命期）**：发生了架构级的重构。**FEAT-0118** 完全重写了 Agent CLI，引入了“角色（Role）- 会话（Session）”分离的运行模型。**FEAT-0121** 确立了 "Flow Skills" 标准，使用 Mermaid 图表作为可执行代码（Design as Code），实现了 Kimi CLI 与通用 Agent 的双重兼容。此外，Memo 系统（FEAT-0119）和治理系统（FEAT-0113/0115）也得到了核心增强。
+- **1月26日（维护期）**：重点在于稳固基础。团队发布了多个补丁版本 (0.3.4, 0.3.5)，优化了 Issue 生命周期管理（FEAT-0108），并增强了跨项目引用能力（FEAT-0107）。这一天的活动表现为典型的工程维护和渐进式改进。
+- **1月30日（革命期）**：发生了架构级的重构。**FEAT-0118** 完全重写了 Agent CLI，引入了“角色（Role）- 会话（Session）”分离的运行模型。**FEAT-0121** 确立了 "Flow Skills" 标准，使用 Mermaid 图表作为可执行代码（Design as Code），实现了 Kimi CLI 与通用 Agent 的双重兼容。此外，Memo 系统（FEAT-0119）和治理系统（FEAT-0113/0115）也得到了核心增强。
 
 **关键发现**: 2026 年 2 月 1 日（即调查当日），项目执行了一次大规模的“历史归档”操作，大量 Feature Issue 被移动至 `.archives/` 目录。本次调查通过 Git 历史回溯技术，成功还原了这些关键特性的设计原貌。
 
@@ -33,18 +33,22 @@
 这一天的活动主要集中在提升系统的稳定性和易用性，为后续的大规模重构清理障碍。
 
 ### 3.1 发布工程 (Release Engineering)
+
 团队在一天内进行了两次版本发布：
-*   **v0.3.4**: 常规修复。
-*   **v0.3.5**: 紧随其后的补丁，可能是为了修复紧急的 Linter 或依赖问题。
-*   **Git Spike**: 引入了 `chore: add git spike` (307378f)，这表明团队开始系统性地研究 Git 交互模式，为后来的 `git_service.py` 奠定基础。
+
+- **v0.3.4**: 常规修复。
+- **v0.3.5**: 紧随其后的补丁，可能是为了修复紧急的 Linter 或依赖问题。
+- **Git Spike**: 引入了 `chore: add git spike` (307378f)，这表明团队开始系统性地研究 Git 交互模式，为后来的 `git_service.py` 奠定基础。
 
 ### 3.2 Issue 生命周期优化 (FEAT-0108)
-*   **背景**: 在此之前，`monoco issue submit` 命令可能包含一个 `--prune` 标志，用于在提交时清理分支。
-*   **变更**: 提交 `2898e04` "remove prune flag from submit command" 移除了这一功能。
-*   **洞察**: 这是一个关键的流程修正。`submit` 仅代表“请求评审”，此时代码尚未合并，分支**绝不应该**被删除。清理工作（Prune）应当且仅应当发生在 `close`（即合并完成）之后。这一变更体现了团队对软件工程生命周期的严谨理解。
+
+- **背景**: 在此之前，`monoco issue submit` 命令可能包含一个 `` 标志，用于在提交时清理分支。
+- **变更**: 提交 `2898e04` "remove prune flag from submit command" 移除了这一功能。
+- **洞察**: 这是一个关键的流程修正。`submit` 仅代表“请求评审”，此时代码尚未合并，分支**绝不应该**被删除。清理工作（Prune）应当且仅应当发生在 `close`（即合并完成）之后。这一变更体现了团队对软件工程生命周期的严谨理解。
 
 ### 3.3 基础设施铺垫
-*   **CHORE-0015 (Agent Prompts)**: "Sync issue best practices to agent prompts"。这表明团队正在尝试让 AI Agent 理解 Monoco 的工作流，这是 "Agent Native" 思想的早期萌芽。
+
+- **CHORE-0015 (Agent Prompts)**: "Sync issue best practices to agent prompts"。这表明团队正在尝试让 AI Agent 理解 Monoco 的工作流，这是 "Agent Native" 思想的早期萌芽。
 
 ---
 
@@ -56,19 +60,19 @@
 
 在此之前，Agent CLI 可能是一系列松散的命令（如 `draft`, `autopsy`）。FEAT-0118 将其重构为结构化的资源管理模型。
 
-*   **新命令体系**:
-    *   `monoco agent run`: 唯一的启动入口。
-    *   `monoco agent session`: 管理运行时实例（List, Kill, Logs）。
-    *   `monoco agent role`: 管理能力模板。
-    *   `monoco agent provider`: 管理底层引擎（Gemini, Claude, Kimi 等）。
-*   **标准化角色 (Standardized Roles)**:
-    代码中明确定义了六大原子角色，构成了 Agent 协作的基石：
-    1.  **Planner**: 架构师，负责拆解 Epic/Feature。
-    2.  **Builder (Engineer)**: 开发者，负责编码与测试。
-    3.  **Reviewer**: 评审者，负责 Code Review 和 QA。
-    4.  **Merger**: 运维，负责合并与发布。
-    5.  **Coroner**: 验尸官，负责错误分析（Autopsy）。
-    6.  **Manager**: 项目经理，负责任务指派与进度追踪。
+- **新命令体系**:
+  - `monoco agent run`: 唯一的启动入口。
+  - `monoco agent session`: 管理运行时实例（List, Kill, Logs）。
+  - `monoco agent role`: 管理能力模板。
+  - `monoco agent provider`: 管理底层引擎（Gemini, Claude, Kimi 等）。
+- **标准化角色 (Standardized Roles)**:
+  代码中明确定义了六大原子角色，构成了 Agent 协作的基石：
+  1.  **Planner**: 架构师，负责拆解 Epic/Feature。
+  2.  **Builder (Engineer)**: 开发者，负责编码与测试。
+  3.  **Reviewer**: 评审者，负责 Code Review 和 QA。
+  4.  **Merger**: 运维，负责合并与发布。
+  5.  **Coroner**: 验尸官，负责错误分析（Autopsy）。
+  6.  **Manager**: 项目经理，负责任务指派与进度追踪。
 
 这一重构将 Monoco 从一个简单的“命令行工具”提升为一个“**Agent 运行时环境**”（Session Manager），支持多 Agent 协作和持久化会话管理。
 
@@ -76,15 +80,15 @@
 
 这是最激动人心的技术创新。团队面临一个挑战：如何让 Kimi CLI（基于自然语言的工具）和通用 Agent（基于 Prompt 的工具）遵循严格的工程标准（如“先测试后提交”）？
 
-*   **解决方案**: **Flow Skills**。
-*   **核心思想**: 使用 **Mermaid 状态机图** 定义工作流。
-*   **实现机制**:
-    *   在 `SKILL.md` 中编写 Mermaid 代码（如 `Investigate -> Code -> Test -> Report -> Submit`）。
-    *   **Kimi CLI 兼容**: 利用 Kimi 的 `/flow` 特性，强制执行状态跳转。
-    *   **通用 Agent 兼容**: 将 Mermaid 图作为 Context 注入 System Prompt，利用 LLM 的图形理解能力实现隐式约束。
-*   **技术细节**:
-    *   引入 `monoco_flow_` 前缀注入机制。由于 Kimi 限制扁平化 Skill，Monoco 动态地将 `resources/skills/flow_engineer` 映射为 `.agent/skills/monoco_flow_engineer`。
-    *   实现了自动 `.gitignore` 管理，防止注入的 Skill 污染用户仓库。
+- **解决方案**: **Flow Skills**。
+- **核心思想**: 使用 **Mermaid 状态机图** 定义工作流。
+- **实现机制**:
+  - 在 `SKILL.md` 中编写 Mermaid 代码（如 `Investigate -> Code -> Test -> Report -> Submit`）。
+  - **Kimi CLI 兼容**: 利用 Kimi 的 `/flow` 特性，强制执行状态跳转。
+  - **通用 Agent 兼容**: 将 Mermaid 图作为 Context 注入 System Prompt，利用 LLM 的图形理解能力实现隐式约束。
+- **技术细节**:
+  - 引入 `monoco_flow_` 前缀注入机制。由于 Kimi 限制扁平化 Skill，Monoco 动态地将 `resources/skills/flow_engineer` 映射为 `.agent/skills/monoco_flow_engineer`。
+  - 实现了自动 `.gitignore` 管理，防止注入的 Skill 污染用户仓库。
 
 ### 4.3 多技能架构 (FEAT-0122 & CHORE-0021)
 
@@ -94,14 +98,16 @@
 
 随着 Agent 能力的增强，管控必须同步跟上。
 
-*   **自动提交 (FEAT-0115 / git_service.py)**: 引入 `IssueGitService`。当 Issue 状态变更（如 `Start`, `Submit`）时，系统自动生成原子提交（Atomic Commit），如 `chore(issue): start FEAT-0118`。这确保了 Git 历史与任务状态的完美同步。
-*   **物理域治理 (FEAT-0113 / validator.py)**: 引入了 `Domain Governance`。对于大规模项目（Issue > 128 或 Epic > 32），强制要求 Issue 关联 `domains` 字段，且子 Issue 必须继承或显式声明域。这防止了单体架构腐化。
-*   **严格分支上下文 (FEAT-0117)**: 强制约束 `create` 必须在 Trunk，`submit` 必须在 Feature Branch。防止了 Agent 在错误的分支上工作。
+- **自动提交 (FEAT-0115 / git_service.py)**: 引入 `IssueGitService`。当 Issue 状态变更（如 `Start`, `Submit`）时，系统自动生成原子提交（Atomic Commit），如 `chore(issue): start FEAT-0118`。这确保了 Git 历史与任务状态的完美同步。
+- **物理域治理 (FEAT-0113 / validator.py)**: 引入了 `Domain Governance`。对于大规模项目（Issue > 128 或 Epic > 32），强制要求 Issue 关联 `domains` 字段，且子 Issue 必须继承或显式声明域。这防止了单体架构腐化。
+- **严格分支上下文 (FEAT-0117)**: 强制约束 `create` 必须在 Trunk，`submit` 必须在 Feature Branch。防止了 Agent 在错误的分支上工作。
 
 ### 4.5 Memo 系统闭环 (FEAT-0119)
+
 Memo（闪念笔记）系统补齐了最后一块拼图：
-*   新增 `monoco memo delete` 命令。
-*   新增 I18n 校验：强制检查 Memo 内容是否符合项目源语言（如中文项目禁止纯英文 Memo），保持知识库语言统一。
+
+- 新增 `monoco memo delete` 命令。
+- 新增 I18n 校验：强制检查 Memo 内容是否符合项目源语言（如中文项目禁止纯英文 Memo），保持知识库语言统一。
 
 ---
 
@@ -116,13 +122,13 @@ class SessionManager:
     def __init__(self, ...):
         # 持久化存储路径 .monoco/sessions/
         self.sessions_dir = self.project_root / ".monoco" / "sessions"
-        
+
     def create_session(self, issue_id: str, role: RoleTemplate) -> RuntimeSession:
         # 生成唯一 Session ID
         session_id = str(uuid.uuid4())
         # 绑定 Git 分支：agent/{issue_id}/{session_id}
         branch_name = f"agent/{issue_id}/{session_id[:8]}"
-        
+
         # 实例化 Worker (执行单元)
         worker = Worker(role, issue_id, timeout=timeout)
         # 包装为运行时会话
@@ -138,9 +144,9 @@ class SessionManager:
 
 1.  **Discovery**: 扫描 `resources/skills/` 寻找 `type: flow` 的 Skill。
 2.  **Injection**: 将其复制到用户的 `.agent/skills/` 目录，并加上 `monoco_flow_` 前缀。
-    *   *Why Prefix?* 为了避免与用户自定义 Skill 冲突，并明确命名空间。
+    - _Why Prefix?_ 为了避免与用户自定义 Skill 冲突，并明确命名空间。
 3.  **Gitignore**: 自动修改 `.gitignore` 添加 `monoco_flow_*/`。
-    *   *Why?* 注入的代码是临时的运行时依赖，不应被提交到用户仓库。
+    - _Why?_ 注入的代码是临时的运行时依赖，不应被提交到用户仓库。
 
 这一机制完美解决了“如何分发标准化工作流到用户本地环境”的问题。
 
@@ -148,11 +154,11 @@ class SessionManager:
 
 `monoco/features/issue/validator.py` 是整个治理系统的核心。它不仅检查语法，还检查**逻辑一致性**：
 
-*   **Time Travel Check**: 确保 `created_at <= opened_at <= closed_at`。
-*   **State Requirement**: 
-    *   如果 Stage 是 `Doing`，必须有 Task Checkbox。
-    *   如果 Stage 是 `Done`，所有 AC 必须打钩 `[x]`。
-*   **Placeholder Check**: 严厉禁止提交包含 `<!-- TODO -->` 或 `<!-- Placeholder -->` 的 Issue。
+- **Time Travel Check**: 确保 `created_at <= opened_at <= closed_at`。
+- **State Requirement**:
+  - 如果 Stage 是 `Doing`，必须有 Task Checkbox。
+  - 如果 Stage 是 `Done`，所有 AC 必须打钩 `[x]`。
+- **Placeholder Check**: 严厉禁止提交包含 `<!-- TODO -->` 或 `<!-- Placeholder -->` 的 Issue。
 
 ---
 
@@ -160,17 +166,19 @@ class SessionManager:
 
 从 1 月 26 日到 1 月 30 日，Monoco Toolkit 完成了一次惊人的蜕变。
 
-*   **Before (1/26)**: 一个辅助开发者管理 Issue 的 CLI 工具。
-*   **After (1/30)**: 一个 **Agent Native 操作系统**。它不仅管理任务，还管理**执行任务的数字员工 (Agents)**，并为它们定义了**标准作业程序 (SOP/Flows)**。
+- **Before (1/26)**: 一个辅助开发者管理 Issue 的 CLI 工具。
+- **After (1/30)**: 一个 **Agent Native 操作系统**。它不仅管理任务，还管理**执行任务的数字员工 (Agents)**，并为它们定义了**标准作业程序 (SOP/Flows)**。
 
 **核心哲学转变**:
 从 "Tool for Humans" 转变为 "Environment for Agents"。Monoco 不再只是被动等待人类输入命令，而是主动提供环境、规则和工作流，让 Agent 能够自治地（Autonomously）完成软件工程任务。
 
 **未来展望**:
 基于 2 月 1 日的大归档和当前的架构，预计下一个版本将重点关注：
+
 1.  **多 Agent 协同**: 基于 SessionManager 实现多个 Role 的并行协作。
 2.  **LSP 深度集成**: 将 Flow Skills 的状态机实时反馈到 IDE 中。
 3.  **知识引擎**: Memo 系统可能会演化为 Agent 的长期记忆（Long-term Memory）。
 
 ---
-*报告生成完毕。*
+
+_报告生成完毕。_

monoco_toolkit-0.4.0/CHANGELOG.md

@@ -0,0 +1,99 @@
+# Changelog
+
+Generated on 2026-02-04
+
+## [v0.4.0] - Recent Releases
+
+### FEAT-0179: 治理与简化 Skill 体系：Role/Workflow 融合与 JIT 劝导
+- *Result*: implemented # implemented, cancelled, wontfix, duplicate
+
+### FEAT-0178: Add --debug flag to monoco sync and is_debug to hook metadata
+- *Result*: implemented # implemented, cancelled, wontfix, duplicate
+
+### FEAT-0176: Universal Hooks: Agent Hooks with ACL
+- *Result*: implemented
+
+### FEAT-0175: Universal Hooks: Git Hooks Dispatcher
+- *Result*: implemented
+
+### FEAT-0174: Universal Hooks: Core Models and Parser
+- *Result*: implemented
+
+### FEAT-0172: 优化 issue close 时的文件合并策略：直接覆盖主线 issue ticket
+- *Result*: implemented
+
+### FEAT-0167: IM 基础设施：核心数据模型与存储
+- *Result*: implemented
+
+### FEAT-0166: Daemon Process Management & Service Governance
+- *Result*: implemented
+
+### FEAT-0165: 重构 Memo Inbox 为信号队列模型：消费即销毁
+- *Result*: implemented
+
+### FEAT-0164: 重构：清除旧 Handler 架构，统一事件驱动架构
+- *Result*: implemented
+
+### FEAT-0163: 在 issue submit 运行过程中自动执行 sync-files
+- *Result*: implemented
+
+### FEAT-0162: Agent 联调工作流 - 端到端自动化
+- *Result*: implemented
+
+### FEAT-0161: 文件系统事件到业务事件的自动化映射框架
+- *Result*: implemented
+
+### FEAT-0160: AgentScheduler 抽象层与 Provider 解耦
+- *Result*: implemented
+
+### FEAT-0155: 重构 Agent 调度架构：事件驱动 + 去链式化
+- *Result*: implemented
+
+### FEAT-0154: 优化 Git 合并策略与增强 Issue 关闭流程
+- *Result*: implemented
+
+### FEAT-0153: Monoco Mailroom: Automated Ingestion & Environment Discovery
+- *Result*: implemented
+
+### FEAT-0152: Monoco Artifact Skills: Multi-modal Document Processing SOP
+- *Result*: implemented
+
+### FEAT-0151: Monoco Artifact Core: Metadata Registry and CAS Storage
+- *Result*: implemented
+
+### FEAT-0148: Issue Module Skill 原子化重构
+- *Result*: implemented
+
+### FEAT-0147: 在 CLI 上实现 Memo 到 Issue 的关联
+- *Result*: implemented
+
+### FEAT-0146: 实现 Issue 域管理 CLI 命令
+- *Result*: implemented
+
+### FEAT-0145: 集成 Git Hooks 到开发工作流
+- *Result*: implemented
+
+### FEAT-0144: Enforce Strict Status and Directory Consistency in Issue Linter
+- *Result*: implemented
+
+### FEAT-0143: Support Block-Level Language Detection in i18n Linter
+- *Result*: implemented
+
+### FEAT-0142: Implement Monoco Toolkit Root Structure
+- *Result*: implemented
+
+### FEAT-0141: Native Git Hooks Management Integration
+- *Result*: cancelled
+
+### FEAT-0140: Monoco Daemon Orchestrator
+- *Result*: cancelled
+
+### FEAT-0138: 实现代理会话持久化
+- *Result*: implemented
+
+### FEAT-0137: Unified Module Loader and Lifecycle Management
+- *Result*: implemented
+
+### FEAT-0134: Monoco Cockpit - Settings Page Implementation
+- *Result*: implemented
+

monoco_toolkit-0.4.0/CLAUDE.md

@@ -0,0 +1,178 @@
+<!--
+⚠️ IMPORTANT: This file is partially managed by Monoco.
+- Content between MONOCO_GENERATED_START and MONOCO_GENERATED_END is auto-generated.
+- Do NOT manually edit the managed block.
+- Do NOT add content after MONOCO_GENERATED_END (use separate files instead).
+-->
+
+<!-- MONOCO_GENERATED_START -->
+## Monoco Toolkit
+
+> **Auto-Generated**: This section is managed by Monoco. Do not edit manually.
+
+### Agent
+
+###### Monoco 核心
+
+项目管理的核心工具包命令。
+
+- **初始化**: `monoco init` (初始化新的 Monoco 项目)
+- **配置**: `monoco config get|set <key> [value]` (管理配置)
+- **同步**: `monoco sync` (与 agent 环境同步)
+- **卸载**: `monoco uninstall` (清理 agent 集成)
+
+---
+
+##### ⚠️ Agent 必读: Git 工作流
+
+在修改任何代码前,**必须**遵循以下步骤:
+
+###### 标准流程
+
+1. **创建 Issue**: `monoco issue create feature -t "功能标题"`
+2. **🔒 启动隔离环境**: `monoco issue start FEAT-XXX --branch`
+   - ⚠️ **强制要求** `--branch` 参数
+   - ❌ 禁止在 `main`/`master` 分支直接修改代码
+3. **实现功能**: 正常编码和测试
+4. **同步文件**: `monoco issue sync-files` (提交前必须运行)
+5. **提交审查**: `monoco issue submit FEAT-XXX`
+6. **关闭 Issue**: `monoco issue close FEAT-XXX --solution implemented`
+
+###### 质量门禁
+
+- Git Hooks 会自动运行 `monoco issue lint` 和测试
+- 不要使用 `git commit --no-verify` 绕过检查
+- Linter 会阻止在受保护分支上的直接修改
+
+> 📖 详见 `monoco-issue` skill 获取完整工作流文档。
+
+### Issue Management
+
+#### Issue 管理
+
+使用 `monoco issue` 管理任务。
+
+- **创建**: `monoco issue create <type> -t "标题"`
+- **状态**: `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. **创建**: `monoco issue create feature -t "标题"`
+2. **启动**: `monoco issue start FEAT-XXX --branch`
+3. **实现**: 正常编码与测试。
+4. **同步**: `monoco issue sync-files` (更新 `files` 字段)。
+5. **提交**: `monoco issue submit FEAT-XXX`。
+6. **合规合并**: `monoco issue close FEAT-XXX --solution implemented` (合并到主线的唯一途径)。
+
+##### Git 合并策略
+
+- **禁止手动合并**: 严禁在 `main`/`master` 分支执行 `git merge` 或直接 `git pull`。
+- **原子合并**: `monoco issue close` 仅根据 Issue 的 `files` 列表合并变更。
+- **冲突处理**: 若产生冲突，请遵循 `close` 命令产生的指引进行手动 Cherry-Pick。
+- **清理策略**: `monoco issue close` 默认执行清理（删除分支/Worktree）。需保留请指定 `--no-prune`。
+
+### Memo (Fleeting Notes)
+
+轻量级笔记，用于快速记录想法。**信号队列模型** (FEAT-0165)。
+
+####### 信号队列语义
+
+- **Memo 是信号，不是资产** - 其价值在于触发行动
+- **文件存在 = 信号待处理** - Inbox 有未处理的 memo
+- **文件清空 = 信号已消费** - Memo 在处理后被删除
+- **Git 是档案** - 历史记录在 git 中，不在应用状态里
+
+####### 命令
+
+- **添加**: `monoco memo add "内容" [-c 上下文]` - 创建信号
+- **列表**: `monoco memo list` - 显示待处理信号（已消费的 memo 在 git 历史中）
+- **删除**: `monoco memo delete <id>` - 手动删除（通常自动消费）
+- **打开**: `monoco memo open` - 直接编辑 inbox
+
+####### 工作流
+
+1. 将想法捕获为 memo
+2. 当阈值（5个）达到时，自动触发 Architect
+3. Memo 被消费（删除）并嵌入 Architect 的 prompt
+4. Architect 从 memo 创建 Issue
+5. 不需要"链接"或"解决" memo - 消费后即消失
+
+####### 指南
+
+- 使用 Memo 记录** fleeting 想法** - 可能成为 Issue 的事情
+- 使用 Issue 进行**可操作的工作** - 结构化、可跟踪、有生命周期
+- 永远不要手动将 memo 链接到 Issue - 如果重要，创建一个 Issue
+
+### 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 的智能层。
+
+### Spike (Research)
+
+###### Spike (研究)
+
+管理外部参考仓库。
+
+- **添加仓库**: `monoco spike add <url>` (在 `.reference/<name>` 中可读)
+- **同步**: `monoco spike sync` (运行以下载内容)
+- **约束**: 永远不要编辑 `.reference/` 中的文件。将它们视为只读的外部知识。
+
+### Artifacts & Mailroom
+
+Monoco Artifacts 系统提供了多模态产物的生命周期管理能力，包括：
+
+1. **内容寻址存储 (CAS)**: 所有产物存储在全局池 `~/.monoco/artifacts` 中，基于内容的 SHA256 哈希值进行寻址和去重。
+2. **自动化摄取 (Mailroom)**: 通过监听 `.monoco/dropzone/` 目录，自动触发文档（Office, PDF 等）到 WebP 的转换流程。
+3. **环境追踪**: 自动探测系统中的 `LibreOffice`, `PyMuPDF` 等工具链。
+4. **元数据管理**: 项目本地维护 `manifest.jsonl`，记录所有产物的类型、哈希及创建时间。
+
+###### 常用操作建议
+
+- **上传文档**: 建议将原始文档放入 `.monoco/dropzone/`，等待 Mailroom 自动完成转换并注册为 Artifact。
+- **查看产物**: 检查 `.monoco/artifacts/manifest.jsonl` 获取当前可用的产物列表。
+- **引用产物**: 在多模态分析时，可以使用产物的 ID 或本地软链接路径。
+
+### Documentation I18n
+
+###### 文档国际化
+
+管理国际化。
+
+- **扫描**: `monoco i18n scan` (检查缺失的翻译)
+- **结构**:
+  - 根文件: `FILE_ZH.md`
+  - 子目录: `folder/zh/file.md`
+
+<!-- MONOCO_GENERATED_END -->