monoco-toolkit 0.3.5__py3-none-any.whl → 0.3.9__py3-none-any.whl

monoco/features/memo/cli.py

@@ -0,0 +1,112 @@
+import typer
+from pathlib import Path
+from typing import Optional
+from rich.console import Console
+from rich.table import Table
+from monoco.core.config import get_config
+from .core import add_memo, list_memos, delete_memo, get_inbox_path, validate_content_language
+
+app = typer.Typer(help="Manage memos (fleeting notes).")
+console = Console()
+
+
+def get_issues_root(config=None) -> Path:
+    if config is None:
+        config = get_config()
+    # Resolve absolute path for issues
+    from monoco.core.config import find_monoco_root
+
+    project_root = find_monoco_root()
+    return project_root / config.paths.issues
+
+
+@app.command("add")
+def add_command(
+    content: str = typer.Argument(..., help="The content of the memo."),
+    context: Optional[str] = typer.Option(
+        None, "--context", "-c", help="Context reference (e.g. file:line)."
+    ),
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Bypass i18n language validation."
+    ),
+):
+    """
+    Capture a new idea or thought into the Memo Inbox.
+    """
+    config = get_config()
+    issues_root = get_issues_root(config)
+
+    # Language Validation
+    source_lang = config.i18n.source_lang
+    if not force and not validate_content_language(content, source_lang):
+        console.print(
+            f"[red]Error: Content language mismatch.[/red] Content does not match configured source language: [bold]{source_lang}[/bold]."
+        )
+        console.print(
+            "[yellow]Tip: Use --force to bypass this check if you really want to add this content.[/yellow]"
+        )
+        raise typer.Exit(code=1)
+
+    uid = add_memo(issues_root, content, context)
+
+    console.print(f"[green]✔ Memo recorded.[/green] ID: [bold]{uid}[/bold]")
+
+
+@app.command("list")
+def list_command():
+    """
+    List all memos in the inbox.
+    """
+    issues_root = get_issues_root()
+
+    memos = list_memos(issues_root)
+
+    if not memos:
+        console.print("No memos found. Use `monoco memo add` to create one.")
+        return
+
+    table = Table(title="Memo Inbox")
+    table.add_column("ID", style="cyan", no_wrap=True)
+    table.add_column("Timestamp", style="magenta")
+    table.add_column("Content")
+
+    for memo in memos:
+        # Truncate content for list view
+        content_preview = memo["content"].split("\n")[0]
+        if len(memo["content"]) > 50:
+            content_preview = content_preview[:47] + "..."
+
+        table.add_row(memo["id"], memo["timestamp"], content_preview)
+
+    console.print(table)
+
+
+@app.command("open")
+def open_command():
+    """
+    Open the inbox file in the default editor.
+    """
+    issues_root = get_issues_root()
+    inbox_path = get_inbox_path(issues_root)
+
+    if not inbox_path.exists():
+        console.print("[yellow]Inbox does not exist yet.[/yellow]")
+        return
+
+    typer.launch(str(inbox_path))
+
+
+@app.command("delete")
+def delete_command(
+    memo_id: str = typer.Argument(..., help="The ID of the memo to delete.")
+):
+    """
+    Delete a memo from the inbox by its ID.
+    """
+    issues_root = get_issues_root()
+
+    if delete_memo(issues_root, memo_id):
+        console.print(f"[green]✔ Memo [bold]{memo_id}[/bold] deleted successfully.[/green]")
+    else:
+        console.print(f"[red]Error: Memo with ID [bold]{memo_id}[/bold] not found.[/red]")
+        raise typer.Exit(code=1)

monoco/features/memo/core.py

@@ -0,0 +1,146 @@
+import re
+from pathlib import Path
+from datetime import datetime
+from typing import List, Dict, Optional
+import secrets
+
+
+def is_chinese(text: str) -> bool:
+    """Check if the text contains at least one Chinese character."""
+    return any("\u4e00" <= char <= "\u9fff" for char in text)
+
+
+def validate_content_language(content: str, source_lang: str) -> bool:
+    """
+    Check if content matches source language using simple heuristics.
+    Returns True if matched or if detection is not supported for the lang.
+    """
+    if source_lang == "zh":
+        return is_chinese(content)
+    # For 'en', we generally allow everything but could be more strict.
+    # Requirement is mainly about enforcing 'zh' when configured.
+    return True
+
+
+def get_memos_dir(issues_root: Path) -> Path:
+    """
+    Get the directory for memos.
+    Convention: Sibling of Issues directory.
+    """
+    # issues_root is usually ".../Issues"
+    return issues_root.parent / "Memos"
+
+
+def get_inbox_path(issues_root: Path) -> Path:
+    return get_memos_dir(issues_root) / "inbox.md"
+
+
+def generate_memo_id() -> str:
+    """Generate a short 6-char ID."""
+    return secrets.token_hex(3)
+
+
+def format_memo(uid: str, content: str, context: Optional[str] = None) -> str:
+    timestamp = datetime.now().strftime("%Y-%m-%d %H:%M:%S")
+    header = f"## [{uid}] {timestamp}"
+
+    body = content.strip()
+
+    if context:
+        body = f"> **Context**: `{context}`\n\n{body}"
+
+    return f"\n{header}\n{body}\n"
+
+
+def add_memo(issues_root: Path, content: str, context: Optional[str] = None) -> str:
+    """
+    Append a memo to the inbox.
+    Returns the generated UID.
+    """
+    inbox_path = get_inbox_path(issues_root)
+
+    if not inbox_path.exists():
+        inbox_path.parent.mkdir(parents=True, exist_ok=True)
+        inbox_path.write_text("# Monoco Memos Inbox\n", encoding="utf-8")
+
+    uid = generate_memo_id()
+    entry = format_memo(uid, content, context)
+
+    with inbox_path.open("a", encoding="utf-8") as f:
+        f.write(entry)
+
+    return uid
+
+
+def list_memos(issues_root: Path) -> List[Dict[str, str]]:
+    """
+    Parse memos from inbox.
+    """
+    inbox_path = get_inbox_path(issues_root)
+    if not inbox_path.exists():
+        return []
+
+    content = inbox_path.read_text(encoding="utf-8")
+
+    # Regex to find headers: ## [uid] timestamp
+    # We split by headers
+
+    pattern = re.compile(r"^## \[([a-f0-9]+)\] (.*?)$", re.MULTILINE)
+
+    memos = []
+    matches = list(pattern.finditer(content))
+
+    for i, match in enumerate(matches):
+        uid = match.group(1)
+        timestamp = match.group(2)
+
+        start = match.end()
+        end = matches[i + 1].start() if i + 1 < len(matches) else len(content)
+
+        body = content[start:end].strip()
+
+        memos.append({"id": uid, "timestamp": timestamp, "content": body})
+
+    return memos
+
+
+def delete_memo(issues_root: Path, memo_id: str) -> bool:
+    """
+    Delete a memo by its ID.
+    Returns True if deleted, False if not found.
+    """
+    inbox_path = get_inbox_path(issues_root)
+    if not inbox_path.exists():
+        return False
+
+    content = inbox_path.read_text(encoding="utf-8")
+    pattern = re.compile(r"^## \[([a-f0-9]+)\] (.*?)$", re.MULTILINE)
+
+    matches = list(pattern.finditer(content))
+    target_idx = -1
+    for i, m in enumerate(matches):
+        if m.group(1) == memo_id:
+            target_idx = i
+            break
+
+    if target_idx == -1:
+        return False
+
+    # Find boundaries
+    start = matches[target_idx].start()
+    # Include the potential newline before the header if it exists
+    if start > 0 and content[start - 1] == "\n":
+        start -= 1
+
+    if target_idx + 1 < len(matches):
+        end = matches[target_idx + 1].start()
+        # Back up if there's a newline before the next header that we should keep?
+        # Actually, if we delete a memo, we should probably remove one "entry block".
+        # Entry blocks are format_memo: \n## header\nbody\n
+        # So we want to remove the leading \n and the trailing parts.
+    else:
+        end = len(content)
+
+    new_content = content[:start] + content[end:]
+    inbox_path.write_text(new_content, encoding="utf-8")
+    return True

monoco/features/memo/resources/skills/note_processing_workflow/SKILL.md

@@ -0,0 +1,140 @@
+---
+name: note-processing-workflow
+description: Memo 笔记处理工作流 (Flow Skill)。定义从捕获 fleeting notes 到组织归档的标准操作流程，确保想法有效管理。
+type: flow
+domain: memo
+version: 1.0.0
+---
+
+# Note Processing Workflow
+
+Memo 笔记处理的标准化工作流，确保 "Capture → Process → Organize → Archive/Convert" 流程。
+
+## 工作流状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Capture: 想法闪现
+    
+    Capture --> Process: 定期整理
+    Capture --> Capture: 继续记录
+    
+    Process --> Organize: 分类完成
+    Process --> Archive: 无价值<br/>(直接归档)
+    
+    Organize --> Convert: 可执行
+    Organize --> Organize: 需补充<br/>(完善信息)
+    Organize --> Archive: 纯参考<br/>(归档保存)
+    
+    Convert --> [*]: 转为 Issue
+    
+    Archive --> [*]: 归档完成
+```
+
+## 执行步骤
+
+### 1. Capture (捕获)
+
+- **目标**: 快速记录 fleeting ideas，不中断当前工作
+- **输入**: 想法、灵感、代码片段、链接
+- **输出**: Memo 记录
+- **检查点**:
+  - [ ] 使用 `monoco memo add "内容"`
+  - [ ] 保持简洁，无需详细描述
+  - [ ] 添加上下文（`-c file:line` 如适用）
+  - [ ] 不中断当前任务流
+
+### 2. Process (处理)
+
+- **目标**: 定期回顾和分类 Memo
+- **策略**: 定期整理（每日/每周）
+- **检查点**:
+  - [ ] 运行 `monoco memo list` 查看所有 Memo
+  - [ ] 评估每个 Memo 的价值
+  - [ ] 分类：可执行 / 纯参考 / 无价值
+  - [ ] 补充缺失信息
+
+### 3. Organize (组织)
+
+- **目标**: 对有价值的 Memo 进行结构化整理
+- **策略**: 根据类型选择处理方式
+- **检查点**:
+  - [ ] 为相关 Memo 添加标签或分类
+  - [ ] 合并相似的 Memo
+  - [ ] 完善模糊的记录
+  - [ ] 设置优先级（如适用）
+
+### 4. Archive/Convert (归档或转化)
+
+- **目标**: 处理完毕的 Memo 归档或转化为 Issue
+- **检查点**:
+  - [ ] **Convert**: 可执行的想法转为 Issue
+    - 使用 `monoco issue create feature/chore/fix -t "标题"`
+    - 在 Issue 中引用原始 Memo
+  - [ ] **Archive**: 纯参考内容归档保存
+    - 移动到知识库或文档
+    - 从 Memo 列表中移除
+  - [ ] **Delete**: 无价值的 Memo 直接删除
+
+## 决策分支
+
+| 条件 | 动作 |
+|------|------|
+| 想法可执行 | Convert，创建 Issue |
+| 纯参考资料 | Archive，保存到知识库 |
+| 无价值/过时 | Delete，直接删除 |
+| 信息不完整 | 返回 Organize，补充信息 |
+
+## 合规要求
+
+- **必须**: Memo 是临时的，不应无限堆积
+- **必须**: 可执行的想法必须转为 Issue 追踪
+- **建议**: 定期处理（建议每周）
+- **建议**: 保持 Memo 简洁，避免长篇大论
+
+## 相关命令
+
+```bash
+# 添加 Memo
+monoco memo add "考虑使用 Redis 缓存用户会话"
+
+# 带上下文的 Memo
+monoco memo add "递归可能导致栈溢出" -c "src/utils.py:42"
+
+# 查看所有 Memo
+monoco memo list
+
+# 编辑 Memo
+monoco memo open
+
+# 创建 Issue（转化 Memo）
+monoco issue create feature -t "实现 Redis 缓存"
+```
+
+## 使用场景
+
+| 场景 | 使用 Memo | 后续处理 |
+|------|-----------|----------|
+| 代码审查时的改进建议 | `memo add "重构建议: ..."` | Process → Convert to Issue |
+| 会议中的临时想法 | `memo add "想法: ..."` | Process → Organize → Convert |
+| 有用的代码片段 | `memo add "Snippet: ..."` | Process → Archive to 知识库 |
+| 技术文章链接 | `memo add "Read: https://..."` | Process → Archive |
+| Bug 线索 | `memo add "可能的 Bug: ..."` | Process → Convert to Fix Issue |
+
+## 与 Issue 的区别
+
+| 维度 | Memo | Issue |
+|------|------|-------|
+| 目的 | 记录想法 | 追踪任务 |
+| 生命周期 | 临时，需定期清理 | 正式，完整生命周期 |
+| 完成标准 | 归档或转化 | 验收标准通过 |
+| 复杂度 | 简单，一句话 | 详细，有 AC 和 Tasks |
+| 追踪 | 无 | 完整追踪 |
+
+## 最佳实践
+
+1. **及时记录**: 想法闪现时立即记录，避免遗忘
+2. **定期整理**: 每周至少处理一次 Memo 列表
+3. **快速转化**: 有价值的想法尽快转为 Issue
+4. **果断删除**: 过时或无价值的 Memo 果断删除
+5. **保持简洁**: Memo 是速记，不需要详细描述

monoco/features/memo/resources/zh/AGENTS.md

@@ -0,0 +1,8 @@
+### 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.

monoco/features/memo/resources/zh/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: monoco-memo
+description: 轻量级备忘录系统，用于快速记录想法、灵感和临时笔记。与正式的 Issue 系统区分开来。
+---
+
+# Monoco Memo (备忘录)
+
+使用此技能快速捕捉 fleeting notes（ fleeting 想法），无需创建正式的 Issue。
+
+## 何时使用 Memo vs Issue
+
+| 场景 | 使用 | 原因 |
+|------|------|------|
+| 临时想法、灵感 | **Memo** | 不需要追踪、不需要完成状态 |
+| 代码片段、链接收藏 | **Memo** | 快速记录，后续整理 |
+| 会议速记 | **Memo** | 先记录，再提炼成任务 |
+| 可执行的工作单元 | **Issue** | 需要追踪、验收标准、生命周期 |
+| Bug 修复 | **Issue** | 需要记录复现步骤、验证结果 |
+| 功能开发 | **Issue** | 需要设计、分解、交付 |
+
+> **核心原则**: Memos 记录**想法**；Issues 处理**可执行任务**。
+
+## 命令
+
+### 添加备忘录
+
+```bash
+monoco memo add "你的备忘录内容"
+```
+
+可选参数:
+- `-c, --context`: 添加上下文引用（如 `file:line`）
+
+示例:
+```bash
+# 简单记录
+monoco memo add "考虑使用 Redis 缓存用户会话"
+
+# 带上下文的记录
+monoco memo add "这里的递归可能导致栈溢出" -c "src/utils.py:42"
+```
+
+### 查看备忘录列表
+
+```bash
+monoco memo list
+```
+
+显示所有未归档的备忘录。
+
+### 打开备忘录文件
+
+```bash
+monoco memo open
+```
+
+在默认编辑器中打开备忘录文件，用于整理或批量编辑。
+
+## 工作流程
+
+```
+想法闪现 → monoco memo add "..." → 定期整理 → 提炼成 Issue 或归档
+```
+
+1. **捕捉**: 有想法时立即使用 `monoco memo add` 记录
+2. **整理**: 定期（如每日/每周）运行 `monoco memo list` 回顾
+3. **转化**: 将有价值的备忘录转化为正式的 Issue
+4. **归档**: 处理完毕后从备忘录中移除
+
+## 最佳实践
+
+1. **保持简洁**: Memo 是速记，不需要详细描述
+2. **及时转化**: 有价值的想法应尽快转为 Issue，避免遗忘
+3. **定期清理**: Memos 是临时的，不要让它们无限堆积
+4. **使用上下文**: 记录代码相关想法时，使用 `-c` 参数标注位置

monoco/features/spike/resources/skills/research_workflow/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: research-workflow
+description: Spike 研究工作流 (Flow Skill)。定义从添加外部仓库到知识提取和归档的标准操作流程，确保外部知识有效管理。
+type: flow
+domain: spike
+version: 1.0.0
+---
+
+# Research Workflow
+
+Spike 研究的标准化工作流，确保 "Add → Sync → Analyze → Extract → Archive" 流程。
+
+## 工作流状态机
+
+```mermaid
+stateDiagram-v2
+    [*] --> Add: 发现参考仓库
+    
+    Add --> Sync: 添加配置
+    Add --> Add: URL 无效<br/>(重新输入)
+    
+    Sync --> Analyze: 同步完成
+    Sync --> Sync: 同步失败<br/>(网络/权限)
+    
+    Analyze --> Extract: 分析完成
+    Analyze --> Analyze: 内容不符<br/>(重新评估)
+    
+    Extract --> Archive: 知识提取完成
+    
+    Archive --> [*]: 归档完成
+```
+
+## 执行步骤
+
+### 1. Add (添加仓库)
+
+- **目标**: 将外部仓库添加为参考
+- **输入**: 仓库 URL、参考目的
+- **输出**: 配置更新
+- **检查点**:
+  - [ ] 验证仓库 URL 可访问
+  - [ ] 确认仓库与当前项目相关
+  - [ ] 运行 `monoco spike add <url>`
+  - [ ] 检查 `.monoco/config.yaml` 已更新
+
+### 2. Sync (同步)
+
+- **目标**: 下载或更新参考仓库内容
+- **检查点**:
+  - [ ] 运行 `monoco spike sync`
+  - [ ] 验证仓库克隆到 `.references/<name>/`
+  - [ ] 检查同步日志，确认无错误
+  - [ ] 验证文件权限正确（只读）
+
+### 3. Analyze (分析)
+
+- **目标**: 研究参考仓库的结构和内容
+- **策略**: 系统性浏览和标记
+- **检查点**:
+  - [ ] 浏览仓库整体结构
+  - [ ] 识别与当前项目相关的模块
+  - [ ] 标记有价值的代码模式
+  - [ ] 记录架构设计亮点
+
+### 4. Extract (提取知识)
+
+- **目标**: 从参考仓库提取可用知识
+- **策略**: 文档化有价值的发现
+- **检查点**:
+  - [ ] 提取关键代码片段（不修改原文件）
+  - [ ] 记录设计模式和最佳实践
+  - [ ] 创建学习笔记（使用 Memo 或 Issue）
+  - [ ] 标注知识来源（仓库 URL + Commit）
+
+### 5. Archive (归档)
+
+- **目标**: 整理和归档研究成果
+- **检查点**:
+  - [ ] 更新项目文档，引用参考仓库
+  - [ ] 创建知识索引（如需要）
+  - [ ] 运行 `monoco spike list` 验证状态
+  - [ ] 定期清理不再需要的参考
+
+## 决策分支
+
+| 条件 | 动作 |
+|------|------|
+| URL 无效 | 返回 Add，检查 URL 格式 |
+| 同步失败 | 检查网络、权限，重试或跳过 |
+| 内容不相关 | 从配置中移除，重新选择 |
+| 发现重要模式 | 创建 Issue，计划引入项目 |
+
+## 合规要求
+
+- **禁止**: 编辑 `.references/` 中的任何文件
+- **必须**: 所有外部知识必须标注来源
+- **必须**: 定期同步以获取更新
+- **建议**: 只添加高质量、相关的仓库
+
+## 相关命令
+
+```bash
+# 添加参考仓库
+monoco spike add <url>
+
+# 同步所有仓库
+monoco spike sync
+
+# 列出已配置的仓库
+monoco spike list
+
+# 记录研究发现
+monoco memo add "发现: {insight}" -c "spike:{repo_name}"
+```
+
+## 最佳实践
+
+1. **精选选择**: 只添加与项目高度相关的仓库
+2. **只读访问**: 将 `.references/` 视为外部知识库，永不修改
+3. **定期同步**: 每月运行 `monoco spike sync` 获取更新
+4. **知识转化**: 将学到的模式转化为项目的实际改进

monoco/main.py

@@ -166,10 +166,13 @@ app.add_typer(config_cmd.app, name="config", help="Manage configuration")
 app.add_typer(project_cmd.app, name="project", help="Manage projects")
 app.add_typer(workspace_cmd.app, name="workspace", help="Manage workspace")
 
-from monoco.features.scheduler import cli as scheduler_cmd
+from monoco.features.agent import cli as scheduler_cmd
 
-app.add_typer(scheduler_cmd.app, name="agent", help="Manage agent sessions")
-app.add_typer(scheduler_cmd.role_app, name="role", help="Manage agent roles")
+app.add_typer(scheduler_cmd.app, name="agent", help="Manage agent sessions and roles")
+
+from monoco.features.memo import app as memo_app
+
+app.add_typer(memo_app, name="memo", help="Manage fleeting notes (memos)")
 
 
 from monoco.daemon.commands import serve

{monoco_toolkit-0.3.5.dist-info → monoco_toolkit-0.3.9.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: monoco-toolkit
-Version: 0.3.5
+Version: 0.3.9
 Summary: Agent Native Toolkit for Monoco - Task Management & Kanban for AI Agents
 Project-URL: Homepage, https://monoco.io
 Project-URL: Repository, https://github.com/IndenScale/Monoco