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

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

@@ -18,5 +18,7 @@ project:
     monoco-toolkit: https://github.com/IndenScale/monoco-toolkit
     qwen-code: https://github.com/QwenLM/qwen-code
     ralph: https://github.com/snarktank/ralph
+    refly: https://github.com/refly-ai/refly
+    refly-skills: https://github.com/refly-ai/refly-skills
     skills: https://github.com/anthropics/skills
     vibe-kanban: https://github.com/BloopAI/vibe-kanban

{monoco_toolkit-0.3.11 → monoco_toolkit-0.3.12}/AGENTS.md

@@ -66,6 +66,119 @@
      - **清理时机**: 环境清理仅应在 `close` 时执行。**禁止**在 `submit` 阶段清理环境。
      - 修改代码后**必须**更新 `files` 字段（通过 `sync-files` 或手动）。
 
+##### Git 合并策略 (Merge Strategy)
+
+###### 核心原则
+
+为确保 Feature 分支安全合并到主线，避免"旧状态污染主线"问题，必须遵循以下合并策略：
+
+####### 1. 禁止手动 Merge
+
+- **🛑 严禁** Agent 手动执行 `git merge` 合并 Feature 分支
+- **🛑 严禁** 使用 `git pull origin main` 后直接提交
+- **✅ 唯一权威途径**: 必须使用 `monoco issue close` 进行闭环
+
+####### 2. 安全合并流程 (Safe Merge Flow)
+
+正确的 Issue 关闭流程如下：
+
+```bash
+#### 1. 确保当前在 main/master 分支，且代码已合并
+$ git checkout main
+$ git pull origin main
+
+#### 2. 确认 Feature 分支的变更已合并到主线
+####    (通过 PR/MR 或其他代码审查流程)
+
+#### 3. 使用 monoco issue close 关闭 Issue (默认执行 prune)
+$ monoco issue close FEAT-XXXX --solution implemented
+
+#### 4. 如需保留分支，使用 --no-prune
+$ monoco issue close FEAT-XXXX --solution implemented --no-prune
+```
+
+####### 3. 冲突处理原则
+
+当 Feature 分支与主线产生冲突时：
+
+1. **自动合并停止**: 如果 `touched files` (Issue `files` 字段) 与主线产生冲突，自动化工具**必须立即停止合并**，并抛出明确错误。
+
+2. **手动 Cherry-Pick 模式**: 
+   - 错误信息会指示 Agent 转入手动 Cherry-Pick 模式
+   - **核心原则**: 仅挑选属于本 Feature 的有效变更，严禁覆盖主线上无关 Issue 的更新
+   - 使用 `git cherry-pick <commit>` 逐个应用有效提交
+
+3. **Fallback 策略**:
+   ```bash
+###   # 1. 创建临时分支用于解决冲突
+   $ git checkout main
+   $ git checkout -b temp/FEAT-XXXX-resolve
+   
+###   # 2. 逐个 Cherry-Pick 有效提交
+   $ git cherry-pick <commit-hash-1>
+   $ git cherry-pick <commit-hash-2>
+   
+###   # 3. 如有冲突，仅保留本 Feature 的变更
+###   #    放弃任何会覆盖主线上其他 Issue 更新的修改
+   
+###   # 4. 完成后合并临时分支
+   $ git checkout main
+   $ git merge temp/FEAT-XXXX-resolve
+   
+###   # 5. 关闭 Issue
+   $ monoco issue close FEAT-XXXX --solution implemented
+   ```
+
+####### 4. 基于 files 字段的智能合并 (Smart Atomic Merge)
+
+Issue 的 `files` 字段记录了 Feature 分支的真实影响范围 (Actual Impact Scope)：
+
+- **生成方式**: `monoco issue sync-files` 使用 `git diff --name-only base...target` 逻辑
+- **作用**: 作为合并白名单，仅合并列表中的文件，过滤因"旧版本基线"导致的隐性覆盖
+- **限制**: 无法防御显式的误操作修改（如无意中格式化其他 Issue 文件）
+
+**未来增强**: 基于 `files` 列表实现选择性合并逻辑：
+```bash
+#### 选择性合并（规划中）
+$ git checkout main
+$ git checkout feature/FEAT-XXXX -- <files...>
+```
+
+####### 5. 清理策略
+
+- **默认清理**: `monoco issue close` 默认执行 `--prune`，删除 Feature 分支/Worktree
+- **保留分支**: 如需保留分支，显式使用 `--no-prune`
+- **强制清理**: 使用 `--force` 强制删除未完全合并的分支（谨慎使用）
+
+```bash
+#### 默认清理分支
+$ monoco issue close FEAT-XXXX --solution implemented
+#### ✔ Cleaned up: branch:feat/feat-XXXX-xxx
+
+#### 保留分支
+$ monoco issue close FEAT-XXXX --solution implemented --no-prune
+
+#### 强制清理（谨慎）
+$ monoco issue close FEAT-XXXX --solution implemented --force
+```
+
+###### 总结
+
+| 操作 | 命令 | 说明 |
+|------|------|------|
+| 创建 Issue | `monoco issue create feature -t "标题"` | 先创建 Issue 再开发 |
+| 启动开发 | `monoco issue start FEAT-XXXX --branch` | 创建 Feature 分支 |
+| 同步文件 | `monoco issue sync-files` | 更新 files 字段 |
+| 提交评审 | `monoco issue submit FEAT-XXXX` | 进入 Review 阶段 |
+| 关闭 Issue | `monoco issue close FEAT-XXXX --solution implemented` | 唯一合并途径 |
+| 保留分支 | `monoco issue close ... --no-prune` | 关闭但不删除分支 |
+
+> ⚠️ **警告**: 任何绕过 `monoco issue close` 的手动合并操作都可能导致主线状态污染，违反工作流合规要求。
+
+### Git Hooks
+
+
+
 ### Memo (Fleeting Notes)
 
 Lightweight note-taking for ideas and quick thoughts.

{monoco_toolkit-0.3.11 → monoco_toolkit-0.3.12}/CLAUDE.md

@@ -64,6 +64,119 @@
      - **清理时机**: 环境清理仅应在 `close` 时执行。**禁止**在 `submit` 阶段清理环境。
      - 修改代码后**必须**更新 `files` 字段（通过 `sync-files` 或手动）。
 
+##### Git 合并策略 (Merge Strategy)
+
+###### 核心原则
+
+为确保 Feature 分支安全合并到主线，避免"旧状态污染主线"问题，必须遵循以下合并策略：
+
+####### 1. 禁止手动 Merge
+
+- **🛑 严禁** Agent 手动执行 `git merge` 合并 Feature 分支
+- **🛑 严禁** 使用 `git pull origin main` 后直接提交
+- **✅ 唯一权威途径**: 必须使用 `monoco issue close` 进行闭环
+
+####### 2. 安全合并流程 (Safe Merge Flow)
+
+正确的 Issue 关闭流程如下：
+
+```bash
+#### 1. 确保当前在 main/master 分支，且代码已合并
+$ git checkout main
+$ git pull origin main
+
+#### 2. 确认 Feature 分支的变更已合并到主线
+####    (通过 PR/MR 或其他代码审查流程)
+
+#### 3. 使用 monoco issue close 关闭 Issue (默认执行 prune)
+$ monoco issue close FEAT-XXXX --solution implemented
+
+#### 4. 如需保留分支，使用 --no-prune
+$ monoco issue close FEAT-XXXX --solution implemented --no-prune
+```
+
+####### 3. 冲突处理原则
+
+当 Feature 分支与主线产生冲突时：
+
+1. **自动合并停止**: 如果 `touched files` (Issue `files` 字段) 与主线产生冲突，自动化工具**必须立即停止合并**，并抛出明确错误。
+
+2. **手动 Cherry-Pick 模式**: 
+   - 错误信息会指示 Agent 转入手动 Cherry-Pick 模式
+   - **核心原则**: 仅挑选属于本 Feature 的有效变更，严禁覆盖主线上无关 Issue 的更新
+   - 使用 `git cherry-pick <commit>` 逐个应用有效提交
+
+3. **Fallback 策略**:
+   ```bash
+###   # 1. 创建临时分支用于解决冲突
+   $ git checkout main
+   $ git checkout -b temp/FEAT-XXXX-resolve
+   
+###   # 2. 逐个 Cherry-Pick 有效提交
+   $ git cherry-pick <commit-hash-1>
+   $ git cherry-pick <commit-hash-2>
+   
+###   # 3. 如有冲突，仅保留本 Feature 的变更
+###   #    放弃任何会覆盖主线上其他 Issue 更新的修改
+   
+###   # 4. 完成后合并临时分支
+   $ git checkout main
+   $ git merge temp/FEAT-XXXX-resolve
+   
+###   # 5. 关闭 Issue
+   $ monoco issue close FEAT-XXXX --solution implemented
+   ```
+
+####### 4. 基于 files 字段的智能合并 (Smart Atomic Merge)
+
+Issue 的 `files` 字段记录了 Feature 分支的真实影响范围 (Actual Impact Scope)：
+
+- **生成方式**: `monoco issue sync-files` 使用 `git diff --name-only base...target` 逻辑
+- **作用**: 作为合并白名单，仅合并列表中的文件，过滤因"旧版本基线"导致的隐性覆盖
+- **限制**: 无法防御显式的误操作修改（如无意中格式化其他 Issue 文件）
+
+**未来增强**: 基于 `files` 列表实现选择性合并逻辑：
+```bash
+#### 选择性合并（规划中）
+$ git checkout main
+$ git checkout feature/FEAT-XXXX -- <files...>
+```
+
+####### 5. 清理策略
+
+- **默认清理**: `monoco issue close` 默认执行 `--prune`，删除 Feature 分支/Worktree
+- **保留分支**: 如需保留分支，显式使用 `--no-prune`
+- **强制清理**: 使用 `--force` 强制删除未完全合并的分支（谨慎使用）
+
+```bash
+#### 默认清理分支
+$ monoco issue close FEAT-XXXX --solution implemented
+#### ✔ Cleaned up: branch:feat/feat-XXXX-xxx
+
+#### 保留分支
+$ monoco issue close FEAT-XXXX --solution implemented --no-prune
+
+#### 强制清理（谨慎）
+$ monoco issue close FEAT-XXXX --solution implemented --force
+```
+
+###### 总结
+
+| 操作 | 命令 | 说明 |
+|------|------|------|
+| 创建 Issue | `monoco issue create feature -t "标题"` | 先创建 Issue 再开发 |
+| 启动开发 | `monoco issue start FEAT-XXXX --branch` | 创建 Feature 分支 |
+| 同步文件 | `monoco issue sync-files` | 更新 files 字段 |
+| 提交评审 | `monoco issue submit FEAT-XXXX` | 进入 Review 阶段 |
+| 关闭 Issue | `monoco issue close FEAT-XXXX --solution implemented` | 唯一合并途径 |
+| 保留分支 | `monoco issue close ... --no-prune` | 关闭但不删除分支 |
+
+> ⚠️ **警告**: 任何绕过 `monoco issue close` 的手动合并操作都可能导致主线状态污染，违反工作流合规要求。
+
+### Git Hooks
+
+
+
 ### Memo (Fleeting Notes)
 
 Lightweight note-taking for ideas and quick thoughts.

{monoco_toolkit-0.3.11 → monoco_toolkit-0.3.12}/GEMINI.md

@@ -120,6 +120,119 @@ _This file is the root configuration for the Monoco Agent. Read `.agent/GLOSSARY
      - **清理时机**: 环境清理仅应在 `close` 时执行。**禁止**在 `submit` 阶段清理环境。
      - 修改代码后**必须**更新 `files` 字段（通过 `sync-files` 或手动）。
 
+##### Git 合并策略 (Merge Strategy)
+
+###### 核心原则
+
+为确保 Feature 分支安全合并到主线，避免"旧状态污染主线"问题，必须遵循以下合并策略：
+
+####### 1. 禁止手动 Merge
+
+- **🛑 严禁** Agent 手动执行 `git merge` 合并 Feature 分支
+- **🛑 严禁** 使用 `git pull origin main` 后直接提交
+- **✅ 唯一权威途径**: 必须使用 `monoco issue close` 进行闭环
+
+####### 2. 安全合并流程 (Safe Merge Flow)
+
+正确的 Issue 关闭流程如下：
+
+```bash
+#### 1. 确保当前在 main/master 分支，且代码已合并
+$ git checkout main
+$ git pull origin main
+
+#### 2. 确认 Feature 分支的变更已合并到主线
+####    (通过 PR/MR 或其他代码审查流程)
+
+#### 3. 使用 monoco issue close 关闭 Issue (默认执行 prune)
+$ monoco issue close FEAT-XXXX --solution implemented
+
+#### 4. 如需保留分支，使用 --no-prune
+$ monoco issue close FEAT-XXXX --solution implemented --no-prune
+```
+
+####### 3. 冲突处理原则
+
+当 Feature 分支与主线产生冲突时：
+
+1. **自动合并停止**: 如果 `touched files` (Issue `files` 字段) 与主线产生冲突，自动化工具**必须立即停止合并**，并抛出明确错误。
+
+2. **手动 Cherry-Pick 模式**: 
+   - 错误信息会指示 Agent 转入手动 Cherry-Pick 模式
+   - **核心原则**: 仅挑选属于本 Feature 的有效变更，严禁覆盖主线上无关 Issue 的更新
+   - 使用 `git cherry-pick <commit>` 逐个应用有效提交
+
+3. **Fallback 策略**:
+   ```bash
+###   # 1. 创建临时分支用于解决冲突
+   $ git checkout main
+   $ git checkout -b temp/FEAT-XXXX-resolve
+   
+###   # 2. 逐个 Cherry-Pick 有效提交
+   $ git cherry-pick <commit-hash-1>
+   $ git cherry-pick <commit-hash-2>
+   
+###   # 3. 如有冲突，仅保留本 Feature 的变更
+###   #    放弃任何会覆盖主线上其他 Issue 更新的修改
+   
+###   # 4. 完成后合并临时分支
+   $ git checkout main
+   $ git merge temp/FEAT-XXXX-resolve
+   
+###   # 5. 关闭 Issue
+   $ monoco issue close FEAT-XXXX --solution implemented
+   ```
+
+####### 4. 基于 files 字段的智能合并 (Smart Atomic Merge)
+
+Issue 的 `files` 字段记录了 Feature 分支的真实影响范围 (Actual Impact Scope)：
+
+- **生成方式**: `monoco issue sync-files` 使用 `git diff --name-only base...target` 逻辑
+- **作用**: 作为合并白名单，仅合并列表中的文件，过滤因"旧版本基线"导致的隐性覆盖
+- **限制**: 无法防御显式的误操作修改（如无意中格式化其他 Issue 文件）
+
+**未来增强**: 基于 `files` 列表实现选择性合并逻辑：
+```bash
+#### 选择性合并（规划中）
+$ git checkout main
+$ git checkout feature/FEAT-XXXX -- <files...>
+```
+
+####### 5. 清理策略
+
+- **默认清理**: `monoco issue close` 默认执行 `--prune`，删除 Feature 分支/Worktree
+- **保留分支**: 如需保留分支，显式使用 `--no-prune`
+- **强制清理**: 使用 `--force` 强制删除未完全合并的分支（谨慎使用）
+
+```bash
+#### 默认清理分支
+$ monoco issue close FEAT-XXXX --solution implemented
+#### ✔ Cleaned up: branch:feat/feat-XXXX-xxx
+
+#### 保留分支
+$ monoco issue close FEAT-XXXX --solution implemented --no-prune
+
+#### 强制清理（谨慎）
+$ monoco issue close FEAT-XXXX --solution implemented --force
+```
+
+###### 总结
+
+| 操作 | 命令 | 说明 |
+|------|------|------|
+| 创建 Issue | `monoco issue create feature -t "标题"` | 先创建 Issue 再开发 |
+| 启动开发 | `monoco issue start FEAT-XXXX --branch` | 创建 Feature 分支 |
+| 同步文件 | `monoco issue sync-files` | 更新 files 字段 |
+| 提交评审 | `monoco issue submit FEAT-XXXX` | 进入 Review 阶段 |
+| 关闭 Issue | `monoco issue close FEAT-XXXX --solution implemented` | 唯一合并途径 |
+| 保留分支 | `monoco issue close ... --no-prune` | 关闭但不删除分支 |
+
+> ⚠️ **警告**: 任何绕过 `monoco issue close` 的手动合并操作都可能导致主线状态污染，违反工作流合规要求。
+
+### Git Hooks
+
+
+
 ### Memo (Fleeting Notes)
 
 Lightweight note-taking for ideas and quick thoughts.

monoco_toolkit-0.3.12/Issues/Chores/closed/CHORE-0033-simplify-issue-start-by-removing-branch-flag-and-m.md

@@ -0,0 +1,95 @@
+---
+id: CHORE-0033
+uid: 4f5dca
+type: chore
+status: closed
+stage: done
+title: 重构 monoco issue start：移除 --branch 选项并将其设为默认
+created_at: '2026-02-02T21:19:17'
+updated_at: '2026-02-02T22:36:44'
+parent: EPIC-0000
+dependencies: []
+related: []
+domains:
+- Foundation
+tags:
+- '#CHORE-0033'
+- '#EPIC-0000'
+files:
+- Issues/Chores/open/CHORE-0033-simplify-issue-start-by-removing-branch-flag-and-m.md
+criticality: high
+solution: implemented
+opened_at: '2026-02-02T21:19:17'
+closed_at: '2026-02-02T22:36:44'
+isolation:
+  type: branch
+  ref: feat/chore-0033-重构-monoco-issue-start-移除-branch-选项并将其设为默认
+  created_at: '2026-02-02T21:28:25'
+---
+
+## CHORE-0033: 重构 monoco issue start：移除 --branch 选项并将其设为默认
+
+## Objective
+
+### 核心背景
+Monoco 的哲学是 **"Branch is the isolation unit"**。目前 `monoco issue start` 虽然默认开启了 branch 模式，但在文档和 Agent 惯例中仍强制要求显式输入 `--branch`。这种冗余不仅增加了操作负担，也导致协议逻辑显得不够整洁。
+
+### 修改目标
+1. **简化命令**：彻底移除 `start` 命令中的 `--branch` 选项。
+2. **确定性行为**：默认即开启 Branch 模式，仅通过 `--direct` 或 `--worktree` 进行显式切换。
+3. **协议同步**：确保所有 Agent 文档、角色提示词、技能描述与该变更保持全局一致，防止 Agent 产生无效输出。
+
+## Acceptance Criteria
+- [x] `monoco issue start` 彻底移除 `--branch/--no-branch` flag。
+- [x] 默认执行行为保持为：从 TRUNK 创建并切换到 feature branch。
+- [x] `GEMINI.md` 更新，删除“强制要求 --branch”的陈述。
+- [x] 全局搜索并清理包含 `--branch` 参数的 Agent 提示词、Skills 和 Roles 内容。
+- [x] 所有单元测试已适配该变更。
+
+## Technical Tasks
+
+### Phase 1: 系统性调研与影响评估
+- [x] 全局搜索 `monoco issue start` 在项目中的所有引用位置
+- [x] 识别所有依赖 `--branch` 的 Role 提示词和 Skill 指令
+- [x] 检查 CI/CD 或 Hooks 中是否有涉及该 flag 的硬编码
+
+### Phase 2: CLI 核心修改
+- [x] 修改 `monoco/features/issue/commands.py`：
+  - [x] 移除 `--branch` 参数定义
+  - [x] 重构内部逻辑，确保 isolation 模式缺省为 `branch`
+  - [x] 保留 `--direct` 作为特权模式开关
+- [x] 验证 `monoco issue start --help` 的输出正确性
+
+### Phase 3: 宪法与 Agent 协议更新
+- [x] 更新 `GEMINI.md` (及所有 I18n 副本) 中的工作流章节
+- [x] 更新 `.agent/workflows/` 下的指令模板
+- [x] 更新核心 Role 的系统提示词内容（如果存在于代码库中）
+
+### Phase 4: 验证与验收
+- [x] 更新并运行 `tests/features/issue/` 相关的单元测试
+- [x] 模拟 Agent 执行流程，确保其不再输出 `--branch`
+- [x] 提交并闭环 Issue
+
+## Review Comments
+
+### 变更摘要
+
+1. **CLI 核心修改** (`monoco/features/issue/commands.py`):
+   - 移除了 `--branch/--no-branch` 参数定义
+   - 重构内部逻辑：`branch = not (direct or worktree)`，默认即 branch 模式
+   - 保留了 `--direct` 和 `--worktree` 作为显式切换选项
+   - 更新了 docstring，删除了 `--no-branch` 的引用
+
+2. **单元测试更新** (`tests/features/issue/test_cli_logic_start.py`):
+   - `test_start_command_default_branch`: 保持原有测试，验证默认 branch 模式
+   - `test_start_command_direct_mode`: 重命名并更新，测试 `--direct` 模式
+   - `test_start_command_worktree_mode`: 新增测试，验证 `--worktree` 模式
+
+3. **文档更新**:
+   - `GEMINI.md`, `AGENTS.md`, `CLAUDE.md`, `QWEN.md`: 删除所有 `--branch` 强制要求
+   - Agent 资源文件: 更新 skills 和 workflows，移除 `--branch` 参数
+
+### 验证结果
+- 所有单元测试通过
+- `monoco issue start --help` 输出正确，不再显示 `--branch` 选项
+- 全局搜索确认无残留的 `--branch` 参数引用（排除 `.references/` 只读目录）

monoco_toolkit-0.3.12/Issues/Chores/closed/CHORE-0035-/346/266/210/351/231/244-asyncio-iscoroutinefunction-/345/274/203/347/224/250/350/255/246/345/221/212.md

@@ -0,0 +1,41 @@
+---
+id: CHORE-0035
+uid: dc8c24
+type: chore
+status: closed
+stage: done
+title: 消除 asyncio.iscoroutinefunction 弃用警告
+created_at: '2026-02-03T10:41:01'
+updated_at: 2026-02-03 11:12:07
+parent: EPIC-0000
+dependencies: []
+related: []
+domains: []
+tags:
+- '#CHORE-0035'
+- '#EPIC-0000'
+files: []
+criticality: low
+solution: implemented
+opened_at: '2026-02-03T10:41:01'
+closed_at: '2026-02-03T11:12:07'
+---
+
+## CHORE-0035: 消除 asyncio.iscoroutinefunction 弃用警告
+
+## Objective
+替换代码中已弃用的 `asyncio.iscoroutinefunction` 为 `inspect.iscoroutinefunction`，以支持更高版本的 Python 并清理 pytest 警告。
+
+## Acceptance Criteria
+- [x] 所有 `asyncio.iscoroutinefunction` 的调用均已替换为 `inspect.iscoroutinefunction`。
+- [x] 运行 `pytest` 不再出现相关的 `DeprecationWarning`。
+- [x] 现有测试全部通过。
+
+## Technical Tasks
+- [x] 全局搜索 `asyncio.iscoroutinefunction` 的使用点。
+- [x] 在相关文件中引入 `inspect` 模块（如果尚未引入）。
+- [x] 执行替换并验证。
+- [x] 运行性能回归或单元测试确保逻辑未变。
+
+## Review Comments
+所有 `asyncio.iscoroutinefunction` 已成功替换为 `inspect.iscoroutinefunction`。经过验证，`pytest` 运行正常且不再报相关弃用警告。

{monoco_toolkit-0.3.11 → monoco_toolkit-0.3.12}/Issues/Domains/CollaborationBus.md

@@ -8,6 +8,7 @@
   - **Kanban**: 可视化工作流与任务看板
   - **IDE Extension**: 编辑器内集成界面
   - **CLI/Web UI**: 命令行与网页交互界面
+  - **IM Integration**: 钉钉、飞书等即时通讯平台集成
 - **Message Passing**: 异步消息传递机制
   - **Memo**: 快速笔记与想法捕捉
   - **Notification**: 系统通知与提醒

{monoco_toolkit-0.3.11 → monoco_toolkit-0.3.12}/Issues/Epics/open/EPIC-0000-Monoco-Toolkit-Root.md

@@ -15,7 +15,7 @@ tags:
 - root
 - toolkit
 domains: []
-progress: 8/15
+progress: 15/21
 files_count: 0
 ---