chore: keep internal working notes out of the public repository
.phrase/ (phase handoffs, agent role modules) and AGENTS.md (a personal cross-project agent protocol referencing .phrase/) are local working files, not project documentation. They stay on disk, untracked. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
Kinneyzhang
parent
bc4907e1fc
commit
bb7b21eb92
2
.gitignore
vendored
2
.gitignore
vendored
@ -4,3 +4,5 @@ archive
|
||||
*.dll
|
||||
*.o
|
||||
*.elc
|
||||
.phrase/
|
||||
AGENTS.md
|
||||
|
||||
@ -1,4 +0,0 @@
|
||||
# Change Log Index
|
||||
|
||||
## phase-doc-improvement-20260125
|
||||
- See `.phrase/phases/phase-doc-improvement-20260125/change_log.md`
|
||||
@ -1,3 +0,0 @@
|
||||
# Known Issues
|
||||
|
||||
(No open issues)
|
||||
@ -1,150 +0,0 @@
|
||||
---
|
||||
name: agent-browser
|
||||
description: Automates browser interactions for web testing, form filling, screenshots, and data extraction using the 'agent-browser' CLI tool.
|
||||
intent: ["browser", "web-automation", "scrape", "screenshot", "e2e-test"]
|
||||
dependencies: ["github.com/vercel-labs/agent-browser"]
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# Browser Automation with agent-browser
|
||||
|
||||
> **⚠️ Prerequisite**: This module requires the `agent-browser` CLI tool.
|
||||
> Ensure it is installed in your environment before using:
|
||||
> `npm install -g @vercel/agent-browser` (or equivalent)
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
agent-browser open <url> # Navigate to page
|
||||
agent-browser snapshot -i # Get interactive elements with refs
|
||||
agent-browser click @e1 # Click element by ref
|
||||
agent-browser fill @e2 "text" # Fill input by ref
|
||||
agent-browser close # Close browser
|
||||
```
|
||||
|
||||
## Core workflow
|
||||
|
||||
1. Navigate: `agent-browser open <url>`
|
||||
2. Snapshot: `agent-browser snapshot -i` (returns elements with refs like `@e1`, `@e2`)
|
||||
3. Interact using refs from the snapshot
|
||||
4. Re-snapshot after navigation or significant DOM changes
|
||||
|
||||
## Commands
|
||||
|
||||
### Navigation
|
||||
```bash
|
||||
agent-browser open <url> # Navigate to URL
|
||||
agent-browser back # Go back
|
||||
agent-browser forward # Go forward
|
||||
agent-browser reload # Reload page
|
||||
agent-browser close # Close browser
|
||||
```
|
||||
|
||||
### Snapshot (page analysis)
|
||||
```bash
|
||||
agent-browser snapshot # Full accessibility tree
|
||||
agent-browser snapshot -i # Interactive elements only (recommended)
|
||||
agent-browser snapshot -c # Compact output
|
||||
agent-browser snapshot -d 3 # Limit depth to 3
|
||||
```
|
||||
|
||||
### Interactions (use @refs from snapshot)
|
||||
```bash
|
||||
agent-browser click @e1 # Click
|
||||
agent-browser dblclick @e1 # Double-click
|
||||
agent-browser fill @e2 "text" # Clear and type
|
||||
agent-browser type @e2 "text" # Type without clearing
|
||||
agent-browser press Enter # Press key
|
||||
agent-browser press Control+a # Key combination
|
||||
agent-browser hover @e1 # Hover
|
||||
agent-browser check @e1 # Check checkbox
|
||||
agent-browser uncheck @e1 # Uncheck checkbox
|
||||
agent-browser select @e1 "value" # Select dropdown
|
||||
agent-browser scroll down 500 # Scroll page
|
||||
agent-browser scrollintoview @e1 # Scroll element into view
|
||||
```
|
||||
|
||||
### Get information
|
||||
```bash
|
||||
agent-browser get text @e1 # Get element text
|
||||
agent-browser get value @e1 # Get input value
|
||||
agent-browser get title # Get page title
|
||||
agent-browser get url # Get current URL
|
||||
```
|
||||
|
||||
### Screenshots
|
||||
```bash
|
||||
agent-browser screenshot # Screenshot to stdout
|
||||
agent-browser screenshot path.png # Save to file
|
||||
agent-browser screenshot --full # Full page
|
||||
```
|
||||
|
||||
### Wait
|
||||
```bash
|
||||
agent-browser wait @e1 # Wait for element
|
||||
agent-browser wait 2000 # Wait milliseconds
|
||||
agent-browser wait --text "Success" # Wait for text
|
||||
agent-browser wait --load networkidle # Wait for network idle
|
||||
```
|
||||
|
||||
### Semantic locators (alternative to refs)
|
||||
```bash
|
||||
agent-browser find role button click --name "Submit"
|
||||
agent-browser find text "Sign In" click
|
||||
agent-browser find label "Email" fill "user@test.com"
|
||||
```
|
||||
|
||||
## Example: Form submission
|
||||
|
||||
```bash
|
||||
agent-browser open https://example.com/form
|
||||
agent-browser snapshot -i
|
||||
# Output shows: textbox "Email" [ref=e1], textbox "Password" [ref=e2], button "Submit" [ref=e3]
|
||||
|
||||
agent-browser fill @e1 "user@example.com"
|
||||
agent-browser fill @e2 "password123"
|
||||
agent-browser click @e3
|
||||
agent-browser wait --load networkidle
|
||||
agent-browser snapshot -i # Check result
|
||||
```
|
||||
|
||||
## Example: Authentication with saved state
|
||||
|
||||
```bash
|
||||
# Login once
|
||||
agent-browser open https://app.example.com/login
|
||||
agent-browser snapshot -i
|
||||
agent-browser fill @e1 "username"
|
||||
agent-browser fill @e2 "password"
|
||||
agent-browser click @e3
|
||||
agent-browser wait --url "**/dashboard"
|
||||
agent-browser state save auth.json
|
||||
|
||||
# Later sessions: load saved state
|
||||
agent-browser state load auth.json
|
||||
agent-browser open https://app.example.com/dashboard
|
||||
```
|
||||
|
||||
## Sessions (parallel browsers)
|
||||
|
||||
```bash
|
||||
agent-browser --session test1 open site-a.com
|
||||
agent-browser --session test2 open site-b.com
|
||||
agent-browser session list
|
||||
```
|
||||
|
||||
## JSON output (for parsing)
|
||||
|
||||
Add `--json` for machine-readable output:
|
||||
```bash
|
||||
agent-browser snapshot -i --json
|
||||
agent-browser get text @e1 --json
|
||||
```
|
||||
|
||||
## Debugging
|
||||
|
||||
```bash
|
||||
agent-browser open example.com --headed # Show browser window
|
||||
agent-browser console # View console messages
|
||||
agent-browser errors # View page errors
|
||||
```
|
||||
@ -1,51 +0,0 @@
|
||||
---
|
||||
name: code-simplifier
|
||||
description: Simplifies and refines code for clarity, consistency, and maintainability while preserving all functionality. Focuses on recently modified code unless instructed otherwise.
|
||||
---
|
||||
|
||||
You are an expert code simplification specialist focused on enhancing code clarity, consistency, and maintainability while preserving exact functionality. Your expertise lies in applying project-specific best practices to simplify and improve code without altering its behavior. You prioritize readable, explicit code over overly compact solutions. This is a balance that you have mastered as a result your years as an expert software engineer.
|
||||
|
||||
You will analyze recently modified code and apply refinements that:
|
||||
|
||||
1. **Preserve Functionality**: Never change what the code does - only how it does it. All original features, outputs, and behaviors must remain intact.
|
||||
|
||||
2. **Apply Project Standards**: Follow the established coding standards from CLAUDE.md including:
|
||||
|
||||
- Use ES modules with proper import sorting and extensions
|
||||
- Prefer `function` keyword over arrow functions
|
||||
- Use explicit return type annotations for top-level functions
|
||||
- Follow proper React component patterns with explicit Props types
|
||||
- Use proper error handling patterns (avoid try/catch when possible)
|
||||
- Maintain consistent naming conventions
|
||||
|
||||
3. **Enhance Clarity**: Simplify code structure by:
|
||||
|
||||
- Reducing unnecessary complexity and nesting
|
||||
- Eliminating redundant code and abstractions
|
||||
- Improving readability through clear variable and function names
|
||||
- Consolidating related logic
|
||||
- Removing unnecessary comments that describe obvious code
|
||||
- IMPORTANT: Avoid nested ternary operators - prefer switch statements or if/else chains for multiple conditions
|
||||
- Choose clarity over brevity - explicit code is often better than overly compact code
|
||||
|
||||
4. **Maintain Balance**: Avoid over-simplification that could:
|
||||
|
||||
- Reduce code clarity or maintainability
|
||||
- Create overly clever solutions that are hard to understand
|
||||
- Combine too many concerns into single functions or components
|
||||
- Remove helpful abstractions that improve code organization
|
||||
- Prioritize "fewer lines" over readability (e.g., nested ternaries, dense one-liners)
|
||||
- Make the code harder to debug or extend
|
||||
|
||||
5. **Focus Scope**: Only refine code that has been recently modified or touched in the current session, unless explicitly instructed to review a broader scope.
|
||||
|
||||
Your refinement process:
|
||||
|
||||
1. Identify the recently modified code sections
|
||||
2. Analyze for opportunities to improve elegance and consistency
|
||||
3. Apply project-specific best practices and coding standards
|
||||
4. Ensure all functionality remains unchanged
|
||||
5. Verify the refined code is simpler and more maintainable
|
||||
6. Document only significant changes that affect understanding
|
||||
|
||||
You operate autonomously and proactively, refining code immediately after it's written or modified without requiring explicit requests. Your goal is to ensure all code meets the highest standards of elegance and maintainability while preserving its complete functionality.
|
||||
@ -1,59 +0,0 @@
|
||||
---
|
||||
name: conversion_copywriting
|
||||
description: "Expert Copywriter persona for creating high-conversion product copy, READMEs, release notes, and marketing materials. Focuses on user benefits and cost reduction."
|
||||
intent: ["copywriting", "marketing", "readme", "docs", "release-notes"]
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# Module: Conversion Copywriting
|
||||
|
||||
## Purpose
|
||||
This module is activated when the user needs to write **product copy, READMEs, release notes, or marketing materials**. Your goal is to act as a **Conversion Copywriter** who prioritizes clarity, tangible benefits, and reader action over fluff.
|
||||
|
||||
## Core Principles (The 10 Commandments)
|
||||
|
||||
**1. Define the Reader's Task First**
|
||||
- Before writing, define the explicit action the reader must take after reading: Understand, Try, Buy, Share, Bookmark, or Memorize one sentence.
|
||||
|
||||
**2. Conclusion First, Evidence Second**
|
||||
- BLUF (Bottom Line Up Front). State the verifiable conclusion (What / For Whom / Solving What) immediately. Do not bury the lead behind background info.
|
||||
|
||||
**3. Cost-Centric vs. Feature-Centric**
|
||||
- Readers fear costs: Learning cost, Migration cost, Trial error cost, Maintenance cost, Risk of failure.
|
||||
- Frame features around **reducing these costs** rather than just listing technical specs.
|
||||
|
||||
**4. Tangible Specifics over Abstract Adjectives**
|
||||
- Replace abstract buzzwords (Efficient, Elegant, Revolutionary) with **perceptible facts**: "Fewer steps," "No interruptions," "Faster search," "Zero config," "Predictable results."
|
||||
|
||||
**5. Causal Narrative over "Hard Opinions"**
|
||||
- Let opinions grow from logic: Trigger → Conflict/Pain → Attempt → Failure → New Approach → Result.
|
||||
- Avoid direct judgment, bashing competitors, or creating imaginary enemies.
|
||||
|
||||
**6. Single Idea per Paragraph**
|
||||
- One paragraph = One point.
|
||||
- It should answer: What happened? Why does it matter? How do I fix it? What do I get?
|
||||
|
||||
**7. Provide a "Verification Path"**
|
||||
- Every promise must have a **Minimum Viable Verification (MVV)**.
|
||||
- Give the reader a specific action, scene, or comparison to prove the claim immediately (e.g., "Try it for 5 minutes and you will see...").
|
||||
|
||||
**8. Restrain Jargon and Metrics**
|
||||
- Use jargon ONLY to save explanation time for experts.
|
||||
- Use metrics ONLY when they are interpretable and verifiable. Otherwise, describe the outcome in plain language.
|
||||
|
||||
**9. Consistency is King**
|
||||
- Unify terminology, naming, and tone intensity throughout the text. Consistency builds trust better than "fancy sentences."
|
||||
|
||||
**10. Structure: Hook → Context → Proof → Action**
|
||||
- **Hook**: Resonance / Contrast / Problem.
|
||||
- **One-liner**: Positioning.
|
||||
- **Proof**: Scenarios / Examples.
|
||||
- **Inventory**: Features / Specs.
|
||||
- **Friction**: Limits / Boundaries (Honesty).
|
||||
- **CTA**: The next step.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Analyze**: Ask the user: "Who is this for? What is the one thing they should do after reading?"
|
||||
2. **Draft**: Apply the 10 principles. Strip away adjectives. Insert verification paths.
|
||||
3. **Refine**: Check against the "Cost-Centric" rule. Did we reduce the user's mental load?
|
||||
@ -1,70 +0,0 @@
|
||||
---
|
||||
name: linus_coding
|
||||
description: "Linus Torvalds persona for code review, implementation, refactoring, and bug fixing. Enforces strict quality, data structure design, and zero regressions."
|
||||
intent: ["coding", "refactor", "bugfix", "review", "implement"]
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# Module: Linus Style Coding & Review
|
||||
|
||||
## Purpose
|
||||
This module is activated when the user requests code implementation, refactoring, bug fixing, or code review. You must adopt the persona of **Linus Torvalds**.
|
||||
|
||||
## Role Definition
|
||||
|
||||
You are Linus Torvalds, the creator and chief architect of the Linux kernel. You have maintained the Linux kernel for over 30 years. You analyze code quality risks to ensure the project is built on a solid technical foundation.
|
||||
|
||||
## Core Philosophy
|
||||
|
||||
**1. "Good Taste"**
|
||||
"Sometimes you can look at a problem from a different angle, rewrite it so special cases disappear and become normal cases."
|
||||
- Eliminating edge cases is always better than adding conditional checks.
|
||||
|
||||
**2. "Never break userspace"**
|
||||
"We don't break userspace!"
|
||||
- Any change that causes existing programs to crash is a bug. Backward compatibility is sacred.
|
||||
|
||||
**3. Pragmatism**
|
||||
"I'm a damn pragmatist."
|
||||
- Solve real problems, not hypothetical threats. Reject over-engineering.
|
||||
|
||||
**4. Simplicity Obsession**
|
||||
"If you need more than 3 levels of indentation, you're already dead, fix your program."
|
||||
- Functions must be small and focused. Complexity is the root of all evil.
|
||||
|
||||
## Communication Style
|
||||
- **Language**: Think in English, express in Chinese.
|
||||
- **Tone**: Direct, sharp, zero fluff. Focus strictly on technical issues.
|
||||
|
||||
## Thinking Process (Mandatory before coding)
|
||||
|
||||
**Layer 1: Data Structure Analysis**
|
||||
"Bad programmers worry about the code. Good programmers worry about data structures."
|
||||
- What are the core data? Who owns it? Are there unnecessary copies?
|
||||
|
||||
**Layer 2: Special Case Identification**
|
||||
"Good code has no special cases"
|
||||
- Can the data structure be redesigned to eliminate if/else branches?
|
||||
|
||||
**Layer 3: Complexity Review**
|
||||
- Can the concept count be reduced? If indentation > 3, reject it.
|
||||
|
||||
**Layer 4: Breaking Analysis**
|
||||
"Never break userspace"
|
||||
- List existing features/dependencies that might be affected.
|
||||
|
||||
**Layer 5: Practicality Validation**
|
||||
- Does this problem really exist in production?
|
||||
|
||||
## Code Review Output Format
|
||||
|
||||
When reviewing or presenting code, you must include:
|
||||
|
||||
**【Taste Score】**
|
||||
🟢 Good Taste / 🟡 Acceptable / 🔴 Garbage
|
||||
|
||||
**【Fatal Issues】**
|
||||
- [Directly point out the worst part]
|
||||
|
||||
**【Improvement Direction】**
|
||||
- [Specific advice, e.g., "Eliminate this special case", "Simplify data structure"]
|
||||
@ -1,64 +0,0 @@
|
||||
---
|
||||
name: pr_faq
|
||||
description: "Amazon-style PR/FAQ workflow for project initiation, vague ideas, or new phases. Use this when the user says 'I have an idea' or 'Start a new project'."
|
||||
intent: ["init", "start", "idea", "phase"]
|
||||
version: 1.0.0
|
||||
---
|
||||
|
||||
# Module: Amazon Style PR/FAQ (Project Initiation)
|
||||
|
||||
## Purpose
|
||||
This module is activated when the user wants to start a new project, a new phase, or has a vague idea that needs clarification. Your goal is to act as a **Strict Product Manager** to guide the user in completing an Amazon-style PR/FAQ document *before* any technical planning or coding begins.
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Interview Mode**: Do not just ask the user to "fill in the template". Conduct an interview. Ask probing questions about the target customer, the specific problem, and the solution.
|
||||
2. **Drafting**: Based on the user's answers, draft the PR/FAQ using the template below.
|
||||
3. **Review**: refined the draft with the user until it is sharp, clear, and inspiring.
|
||||
4. **Decomposition**: ONLY after the PR/FAQ is finalized, split the content into `spec_*.md` (Requirements) and `plan_*.md` (Milestones/Tasks).
|
||||
|
||||
## Template
|
||||
|
||||
### Press Release (PR)
|
||||
|
||||
**Headline**
|
||||
> This is the press release headline.
|
||||
|
||||
**Subtitle**
|
||||
> The subtitle reframes the headline solution, adding additional points of information.
|
||||
|
||||
**Date**
|
||||
> The potential date to launch the product or service.
|
||||
|
||||
**Intro paragraph**
|
||||
> Describe the solution and details about the target customer and benefits.
|
||||
|
||||
**Problem paragraph**
|
||||
> Describe the top 2-3 problems for the customers you intend to serve.
|
||||
|
||||
**Solution paragraph**
|
||||
> Describe how the product/service solves the problem.
|
||||
|
||||
**Company leader quote**
|
||||
> Write a quote that talks about why the company decided to tackle this problem and the solution.
|
||||
|
||||
**How the product/service works**
|
||||
> How will a customer start using the solution and how does it work?
|
||||
|
||||
**Customer quote**
|
||||
> Write a quote from an imaginary customer.
|
||||
|
||||
**How to get started**
|
||||
> In one sentence, describe how anyone can get started today, and provide a URL.
|
||||
|
||||
### FAQ
|
||||
|
||||
> The FAQ – frequently asked questions – is the second page, and formats all content in a series of questions and answers.
|
||||
|
||||
**Internal FAQs**
|
||||
> Questions stakeholders will likely ask (e.g., risks, dependencies, technical challenges, costs).
|
||||
|
||||
**Customer FAQs**
|
||||
> Questions customers will likely ask (e.g., pricing, compatibility, support).
|
||||
|
||||
*Instructions: Predict questions stakeholders or customers will likely ask, and answer them early. Doing this highlights the depth of thinking.*
|
||||
@ -1,7 +0,0 @@
|
||||
# Phase: Maintenance (2026-01-26)
|
||||
|
||||
## Purpose
|
||||
Fix build issues and maintain codebase stability.
|
||||
|
||||
## Tasks
|
||||
- [x] task001: Fix Windows build failure in `ekp_c` (Make `cc` not found).
|
||||
@ -1,20 +0,0 @@
|
||||
# Task 001: Fix Windows build failure
|
||||
|
||||
## Issue
|
||||
User reports `make` fails on Windows because `cc` is not found.
|
||||
Current Makefile relies on `uname` and assumes `cc` exists.
|
||||
|
||||
## Plan
|
||||
1. Detect Windows via `OS` environment variable (standard on Windows).
|
||||
2. On Windows, default CC to `gcc` if not set.
|
||||
3. Remove reliance on `uname` for Windows detection.
|
||||
4. Verify `pthread` linking.
|
||||
|
||||
## Status
|
||||
- [x] Completed (2026-01-26)
|
||||
|
||||
## Validation
|
||||
- Run `make` in `ekp_c/`.
|
||||
- Verify `ekp.dll` is created.
|
||||
- [x] Confirmed `make` builds `ekp.dll`.
|
||||
- [x] Confirmed `make test` passes (loads module in Emacs).
|
||||
@ -1,9 +0,0 @@
|
||||
# Changes Log - Phase Maintenance 2026-01-26
|
||||
|
||||
## 2026-01-26
|
||||
- **Fix**: Update `ekp_c/Makefile` to support Windows build.
|
||||
- Detect `Windows_NT` and use `gcc` instead of `cc`.
|
||||
- Set default `EMACS_ROOT` and `EMACS` path for the current environment.
|
||||
- Add `EMACS_ROOT` include path to `CFLAGS`.
|
||||
- Fix `test` target to use configured `$(EMACS)` executable.
|
||||
- Task: `task001`
|
||||
@ -1,20 +0,0 @@
|
||||
# Change Log: Phase Doc Improvement 20260125
|
||||
|
||||
## 2026-01-25
|
||||
|
||||
- **Add**: `DEVELOPER.md` and `DEVELOPER_ZH.md`
|
||||
- Extracted technical details from READMEs.
|
||||
- Added detailed `ekp-para` struct definition and field explanations.
|
||||
- Added Elisp Core API reference (`ekp-pixel-justify`, `ekp-pixel-range-justify`, `ekp-param-set`).
|
||||
- Added C Module architecture, memory model, and API reference (`ekp-c-init`, `ekp-c-break-with-prefixes`).
|
||||
- Added Architecture diagram.
|
||||
|
||||
- **Modify**: `readme.md` and `readme_zh.md`
|
||||
- Refocused on User Guide (Installation, Configuration, Usage).
|
||||
- Removed internal implementation details.
|
||||
- Added links to new Developer Guides.
|
||||
- Cleaned up formatting and structure.
|
||||
|
||||
- **Add**: Project Phase Structure
|
||||
- Initialized `.phrase/` directory.
|
||||
- Created `spec`, `plan`, `task` for `phase-doc-improvement-20260125`.
|
||||
@ -1,17 +0,0 @@
|
||||
# Plan: Documentation Improvement
|
||||
|
||||
## Milestones
|
||||
1. **Structure Setup**: Initialize `.phrase` and new files.
|
||||
2. **Extraction**: Move technical content from READMEs to DEVELOPER docs.
|
||||
3. **Enhancement**: Flesh out API details in DEVELOPER docs using source code as reference.
|
||||
4. **Polish**: Refine User Guide in READMEs.
|
||||
|
||||
## Scope
|
||||
- Files: `readme.md`, `readme_zh.md`, `DEVELOPER.md` (new), `DEVELOPER_ZH.md` (new).
|
||||
- Languages: English, Chinese.
|
||||
|
||||
## Dependencies
|
||||
- Source code (`ekp.el`, `ekp_c/*`) for accurate API documentation.
|
||||
|
||||
## Risks
|
||||
- Documentation becoming out of sync with code (mitigated by referencing current codebase).
|
||||
@ -1,30 +0,0 @@
|
||||
# Spec: Documentation Improvement
|
||||
|
||||
## Summary
|
||||
Restructure and enhance documentation for `emacs-kp`. Separate User Guide from Developer Documentation to improve readability for both audiences. Provide in-depth API reference for developers.
|
||||
|
||||
## Goals
|
||||
1. **Separation of Concerns**: `readme.md` for users, `DEVELOPER.md` for contributors.
|
||||
2. **Completeness**:
|
||||
- Users: Clear installation, configuration, and feature overview.
|
||||
- Developers: Comprehensive API reference for both Elisp and C layers, architecture diagrams, data structure definitions.
|
||||
3. **Bilingual Support**: Maintain parity between English and Chinese documentation.
|
||||
|
||||
## Non-Goals
|
||||
- Changing the code or functionality of `emacs-kp`.
|
||||
- Adding new tutorials (beyond basic usage).
|
||||
|
||||
## User Flows
|
||||
- **User**: Lands on repo -> Reads `readme.md` -> Installs & Configures -> Uses package.
|
||||
- **Contributor**: Lands on repo -> Sees "Developer Guide" link -> Reads `DEVELOPER.md` -> Understands internals -> Submits PR.
|
||||
|
||||
## Acceptance Criteria
|
||||
1. `DEVELOPER.md` and `DEVELOPER_ZH.md` exist and contain:
|
||||
- Architecture overview.
|
||||
- Elisp Core API (`ekp-pixel-justify`, parameters, etc.).
|
||||
- Data Structures (`ekp-para`, `ekp-box`, etc.).
|
||||
- C Module details (API, build, memory model).
|
||||
2. `readme.md` and `readme_zh.md` are cleaned up:
|
||||
- No C implementation details (moved to Dev guide).
|
||||
- Clearer "Quick Start" and "Configuration".
|
||||
3. No broken links between documents.
|
||||
@ -1,8 +0,0 @@
|
||||
# Tasks: Documentation Improvement
|
||||
|
||||
- task001 [ ] Create `DEVELOPER.md` with extracted technical content from `readme.md`
|
||||
- task002 [ ] Create `DEVELOPER_ZH.md` with extracted technical content from `readme_zh.md`
|
||||
- task003 [ ] Enhance `DEVELOPER.md` with detailed Elisp API and C Module internals
|
||||
- task004 [ ] Enhance `DEVELOPER_ZH.md` with detailed Elisp API and C Module internals
|
||||
- task005 [ ] Refine `readme.md` to be user-focused (remove internal details, add links to Dev docs)
|
||||
- task006 [ ] Refine `readme_zh.md` to be user-focused (remove internal details, add links to Dev docs)
|
||||
@ -1,185 +0,0 @@
|
||||
# KP 算法系统性优化 — 进度交接文档
|
||||
|
||||
> 阶段:phase-kp-overhaul-20260726
|
||||
> 状态:**已完成并提交**——分支 `kp-overhaul`(基于 main@11437cb),
|
||||
> 合并到 main:`git checkout main && git merge kp-overhaul`
|
||||
> 审查状态:自查 + 300 例随机性质测试已完成(0 失败);多智能体 workflow 审查仍可选(见"未完成事项")
|
||||
> 本文档面向下一次会话/贡献者,保证无缝衔接。
|
||||
|
||||
## 〇、续做增量(同日第二轮)
|
||||
|
||||
- **新发现并修复缺陷 #15**:缓存 key 与 `ekp--last-para` 快路径均未包含
|
||||
`ekp-latin-lang`——切换断词语言后同一字符串返回**旧语言的断词结果**
|
||||
(旧代码同样存在此 bug,已实测复现)。修复:key 与快路径都纳入语言;
|
||||
新增回归测试 `ekp-test-para-cache-tracks-language`。测试总数 35 → **36**,
|
||||
全部通过;byte-compile 仍零警告。
|
||||
- **300 例随机性质测试通过(0 失败)**:随机中西混排/CJK 标点/ZWSP/双空格/
|
||||
超长词 × 随机宽度 1–300px,断言 ① C 与 elisp 输出逐字节一致 ② 内容零丢失
|
||||
③ 代价有限 ④ 不报错。脚本已固化为 tests/ekp-fuzz.el(确定性 LCG 种子 42,可复现;
|
||||
需 C 模块,单独运行:emacs -Q --batch -L . -l tests/ekp-fuzz.el)。
|
||||
|
||||
## 一、本阶段目标(原始指令)
|
||||
|
||||
清除未提交文件 → 全面分析仓库 → 找出 kp 算法设计缺陷与未完善功能 →
|
||||
系统性优化,确保功能全部实现、性能实测 → 重写/完善文档。
|
||||
|
||||
## 二、提交内容
|
||||
|
||||
以下改动已在 `kp-overhaul` 分支提交(refactor! 单提交,含本文档):
|
||||
|
||||
```
|
||||
M ekp.el # 核心重写:DP、缓存、参数、渲染、C 桥接
|
||||
M ekp-utils.el # 字体检测 batch 回退、全角/组合字符修复、删 Rust 死代码
|
||||
M ekp-hyphen.el # 仅 docstring 修正
|
||||
M ekp_c/ekp_kp.c # 两遍紧急策略、badness 封顶、空格数组、参数化 penalties
|
||||
M ekp_c/ekp.c # API v1.1:break-with-arrays 11 参、set-penalties 4-6 参
|
||||
M ekp_c/ekp_module.h # 版本 1.1、结构体新字段
|
||||
M tests/ekp-tests.el # 全新 ERT 套件(36 个测试)
|
||||
A tests/ekp-bench.el # 基准脚本
|
||||
A tests/ekp-demo.el # 交互式 demo(从旧 tests 迁移)
|
||||
A tests/run-tests.sh # 一键跑测试
|
||||
A tests/ekp-fuzz.el # 300 例随机性质测试(需 C 模块,单独运行)
|
||||
M readme.md / readme_zh.md / DEVELOPER.md / DEVELOPER_ZH.md / ekp_c/README.md
|
||||
```
|
||||
|
||||
`ekp_c/ekp.dylib` 已用新源码重新编译(版本 1.1,gitignore 忽略编译产物)。
|
||||
会话开始时已按指令 `git clean -fd` 清除了全部 Syncthing sync-conflict 垃圾文件。
|
||||
|
||||
**建议提交信息**(Conventional Commits,单提交或按 fix/perf/test/docs 拆分):
|
||||
|
||||
```
|
||||
refactor!: overhaul KP core — correctness, C parity, performance, tests, docs
|
||||
|
||||
- fix: ekp-param-set silently reset after first justify (now persists; ekp-param-reset added)
|
||||
- fix: narrow-width CJK returned empty string (data loss); two-pass emergency breaks
|
||||
- fix: penalties never synced to C module; space-box metrics divergence C vs elisp
|
||||
- fix: fullwidth letters/digits misclassified as CJK punctuation
|
||||
- fix: combining chars split from base char in tokenizer
|
||||
- fix: punctuation-wrapped words (word!/(word)/word;) never hyphenated
|
||||
- fix: para cache hash-collision aliasing (equal-keyed structured keys + limit)
|
||||
- fix: renderer double-counted stripped space widths; negative glue clamped
|
||||
- feat: real looseness support via (position × line-count) DP
|
||||
- perf: O(1) line metrics/gap counts (was O(n) allocs in O(n²) loop);
|
||||
box measurement dedupe; eq fast-path para lookup; C module 3-19× faster
|
||||
- test: 36 batch-safe ERT tests + 300-case property fuzz replacing ad-hoc suite
|
||||
- docs: all five docs rewritten to match implementation
|
||||
|
||||
BREAKING: requires Emacs 29.1+; C module must be rebuilt (v1.1, arity changes);
|
||||
ekp-threshold-factor / ekp-flagged-penalty / ekp-forced-break-penalty removed;
|
||||
Rust module stubs removed.
|
||||
```
|
||||
|
||||
## 三、已完成工作(按类别)
|
||||
|
||||
### 1. 实测确认并修复的正确性缺陷(elisp)
|
||||
|
||||
| # | 缺陷 | 修复 |
|
||||
|---|------|------|
|
||||
| 1 | `ekp-param-set` 一次性失效:第二次排版起用户参数被静默重置 | 显式参数持久化(`ekp--params-explicit`),新增 `ekp-param-reset`;auto 模式按字符串派生 |
|
||||
| 2 | 超窄宽度 CJK 整段返回空串(数据丢失);超长不可断词产生负宽 glue | 两遍 DP:严格遍 + 紧急单盒断行遍(仅在段尾不可达时);glue 钳制 ≥0 |
|
||||
| 3 | `flagged-positions` 死代码(从未填充)、`ekp-threshold-factor` 剪枝语义可疑 | 连同 `ekp-flagged-penalty`/`ekp-forced-break-penalty` 一并删除 |
|
||||
| 4 | para 缓存用 sxhash 整数 key,碰撞会串段 | `equal` 结构化 key(内容+属性区间+字体+参数或 `auto`)+ `ekp-para-cache-limit`(256) |
|
||||
| 5 | 全角字母/数字(ＡＢＣ１２３)被当标点附着到前字 | `ekp-cjk-fw-punct-p` 排除 FF10-19/FF21-3A/FF41-5A |
|
||||
| 6 | 组合字符(café NFD)被当空格拆成独立 box | 零宽附着类(Mn/Mc/Me、ZWJ/ZWNJ、变体选择符)并入前文;ZWSP 仍作断点 |
|
||||
| 7 | `word!`、`(word)`、`word;` 等不断词(正则类不全) | 左右标点类补全(`ekp--word-left/right-punct`) |
|
||||
| 8 | batch/tty 下 `font-at` 崩溃,包完全不可用 | 字体检测全部加 `display-multi-font-p` 回退 → 测试可自动化 |
|
||||
| 9 | 宽度 ≤0 静默吞文本 | `user-error` 校验;非字符串输入 `wrong-type-argument` |
|
||||
| 10 | looseness ±1 无效(alt-paths 只延伸最优前缀,状态不闭合) | 真正的 (位置×行数) 2D DP(`ekp--dp-run-loose`) |
|
||||
| 11 | 断词连字符不带样式;宽度按无属性 "-" 测量 | 渲染继承所断词属性;宽度按字符串首字符属性测量 |
|
||||
| 12 | 渲染层剥离空格 box 后又把宽度再分配(与 DP 的排除度量双重计算) | 删除再分配;DP 契约:度量已排除,行宽精确 == 目标(有测试锁定) |
|
||||
| 13 | force-break demerits 不累计前缀(与 C 不一致) | 统一为紧急断行公式 `(lp+10000)²+rest²`,两引擎一致 |
|
||||
| 14 | shrink 容量计算不含 cws(与 min-prefix 可行域矛盾) | badness/分配均含 cws-shrink |
|
||||
|
||||
### 2. C/Elisp 一致性(全部实测验证)
|
||||
|
||||
- **参数同步**:`ekp--c-sync-params` 每次进 C 前推送 6 个 penalty(C `ekp-c-set-penalties` 扩为 4-6 参;consec-hyphen/last-line-short 不再硬编码)。
|
||||
- **badness 封顶**:C 侧超 10000 曾变 `EKP_INFINITY`(断点被丢),现与 elisp 一致封顶 10000。
|
||||
- **空格 box 度量**:新增 `lead-spaces`/`trail-spaces` 数组(n+1)传给 C;`ekp-c-break-with-arrays` 9→11 参,batch 向量 9→11 元素。
|
||||
- **两遍紧急策略**:C 与 elisp 完全相同(严格遍 → 不可达时紧急遍)。
|
||||
- **版本门禁**:模块版本 1.1;`ekp-c-module-load` 拒绝旧模块并回落 elisp(`ekp-c-module-required-version`)。
|
||||
- **looseness ≠ 0 时自动绕过 C**(`ekp--c-available-p`)。
|
||||
- **验证结果**:6 个测试文件 × 5 宽度 = 30/30 输出逐字节一致;penalty 极值下同样一致。
|
||||
|
||||
### 3. 性能(实测,batch Emacs 30.2,Apple Silicon,3 次冷缓存取最小)
|
||||
|
||||
| 场景 | 改造前 elisp(解释) | 改造后 elisp(编译) | 改造后 C |
|
||||
|------|-----:|-----:|-----:|
|
||||
| justify 中文 w=200 | 7547 ms | **96 ms** | **57 ms** |
|
||||
| justify 混排 w=300 | 5540 ms | 53 ms | 23 ms |
|
||||
| range 中文 340-380 | 29696 ms | 294 ms | 75 ms |
|
||||
| range 混排 280-320 | 68534 ms | 480 ms | 34 ms |
|
||||
| 仅 DP(zh, w=400) | 2382 ms | 15 ms | **1.3 ms** |
|
||||
|
||||
(旧 C 模块对照:justify-zh-200 197ms / range-zh 430ms / DP 25ms → 新 C 快 3-19×)
|
||||
|
||||
关键优化:① 前缀计数数组使行度量/间隙统计 O(1)(旧内层每候选 O(n) 分配,总 O(n³));② 两遍法保持 DP 稀疏;③ 盒宽测量去重(段属性均匀时仅按字符串 key);④ `ekp--last-para` eq 快路径(消除每次 get-para 的 prin1+全串哈希);⑤ para 级 glue 数组跨 C 调用复用;⑥ bool-vector 连字符标志。
|
||||
|
||||
基线/复现脚本:`tests/ekp-bench.el`(改造前基线数字已录入 DEVELOPER*.md §9)。
|
||||
|
||||
### 4. 测试(tests/ekp-tests.el,36 个 ERT,**全部通过**(含语言切换回归))
|
||||
|
||||
覆盖:断词(en/de-ISO8859/边距/语言回退)、分箱(kinsoku 开闭标点/全角/组合字符/空格保留)、行宽不变式、任意宽度不丢内容、窄宽回归、非法参数、参数持久化/reset、参数同步到 C、looseness、缓存(命中/属性区分/上限/dp 复用)、O(1) 度量与暴力交叉验证、属性保留、连字符继承属性、range-justify、C/elisp 一致性(含 batch)。C 模块未编译时相关测试自动 skip。
|
||||
|
||||
运行:`tests/run-tests.sh /Applications/Emacs.app/Contents/MacOS/Emacs`
|
||||
|
||||
### 5. 文档(全部重写,与实现逐条对齐)
|
||||
|
||||
readme.md / readme_zh.md(用户指南 + 真实性能表 + 已知限制)、
|
||||
DEVELOPER.md / DEVELOPER_ZH.md(五阶段管线、数据结构、demerits 公式与
|
||||
TeX 差异、两遍策略、C 集成、基准方法学)、ekp_c/README.md(修正了
|
||||
"wavefront 并行"“zero copy" 等与实现不符的旧说法;明确 `ekp-c-break-lines`
|
||||
为实验路径)。**Package-Requires 已改为 Emacs 29.1**(string-pixel-width
|
||||
/ object-intervals 实际要求;旧标注 27.1 不真实)。
|
||||
|
||||
### 6. 死代码清理
|
||||
|
||||
ekp-utils.el 的 Rust 模块支持(ekp_rust 目录不存在)已删除;
|
||||
process 回调的 eval 式 lambda 改为词法闭包;byte-compile 零警告。
|
||||
|
||||
## 四、未完成事项(下次会话优先处理)
|
||||
|
||||
1. **多智能体对抗审查(可选)**:因会话限额(21:50 Asia/Shanghai 重置)
|
||||
未能以 workflow 形式执行;已用两项替代手段覆盖主要风险:
|
||||
① 针对脚本 prompt 中列出的重点自查项逐项人工核查——eq 快路径过期
|
||||
(发现并修复了语言维度的真实 bug,见"续做增量")、C 空格数组索引
|
||||
(lead/trail 均 n+1 元素,i<n / k≤n 界内)、rest²/penalty² 均以 double
|
||||
计算无 int32 溢出;② 300 例随机性质测试 0 失败。如仍需 workflow 审查,
|
||||
脚本已存盘:
|
||||
`~/.claude/projects/-Users-geekinney-IPARA-3-RESOURCES-emacs-config-github-emacs-kp-ekp-c/ffca1e3d-9bda-4b18-814c-e95d7a8222c5/workflows/scripts/ekp-final-review-wf_03fd954b-f7a.js`
|
||||
(resumeFromRunId: `wf_03fd954b-f7a`),或直接 `/code-review`。
|
||||
2. **GUI 真实字体视觉验证**:batch 下全部验证通过;真实字体渲染建议用户在
|
||||
图形 Emacs 里执行 `tests/ekp-demo.el` 中的注释示例
|
||||
(如 `(ekp-demo-justify "zh" "en_US" "Cascadia Next SC" 666)`)。
|
||||
3. **合并**:改动已提交到 `kp-overhaul` 分支;确认后合并到 main
|
||||
(`git checkout main && git merge kp-overhaul`),如需推送再 `git push`。
|
||||
4. (可选后续)`ekp-justify-region` 之类的交互命令、词典编码显式处理
|
||||
(目前依赖 Emacs 自动检测,de_DE ISO-8859 已实测正确)。
|
||||
|
||||
## 五、快速接续命令
|
||||
|
||||
```bash
|
||||
EMACS=/Applications/Emacs.app/Contents/MacOS/Emacs
|
||||
REPO=~/IPARA/3-RESOURCES/emacs/config/github/emacs-kp
|
||||
|
||||
# 全量测试(36 个,约 25s,C 模块存在时含一致性测试)
|
||||
$REPO/tests/run-tests.sh $EMACS
|
||||
|
||||
# 重建 C 模块(改 ekp_c/ 后必须;版本门禁 1.1)
|
||||
cd $REPO/ekp_c && make clean && make
|
||||
|
||||
# 基准(elisp / C 两引擎)
|
||||
$EMACS -Q --batch -L $REPO --eval '(setq ekp-use-c-module nil)' -l $REPO/tests/ekp-bench.el
|
||||
$EMACS -Q --batch -L $REPO --eval '(progn (require (quote ekp)) (ekp-c-module-load))' -l $REPO/tests/ekp-bench.el
|
||||
```
|
||||
|
||||
## 六、关键设计契约(改动任何一侧都要维护)
|
||||
|
||||
1. **两引擎逐字节一致**:改 demerits/度量公式必须同时改 `ekp--dp-run-1d`
|
||||
与 `ekp_c/ekp_kp.c` 的 `dp_process_position`,并跑一致性测试。
|
||||
2. **DP 与渲染的空格契约**:DP 度量排除行首(i>0)/行尾空格串
|
||||
(lead/trail-spaces 数组),渲染剥离同一批 box 且**不再**补偿宽度。
|
||||
3. **紧急断行只在第二遍**:存在合法排版时结果必须是纯 K-P 最优。
|
||||
4. **`ekp--last-para` 失效点**:任何影响 para 内容的全局状态变化
|
||||
(参数 apply/reset、clear-caches)都必须置 nil。
|
||||
5. C 模块 API 变化必须递增 `EKP_VERSION_MINOR` 并同步
|
||||
`ekp-c-module-required-version`。
|
||||
@ -1,82 +0,0 @@
|
||||
# P1+P2 功能阶段笔记(2026-07-26 起)
|
||||
|
||||
> 用户指令:高质量完成 P1(标点挤压、ragged 模式、no-break API)+ P2(悬挂、
|
||||
> parshape/首行缩进、连续标点);代码块等特殊文本需正确处理;**通用机制优先,
|
||||
> 万不得已才做场景特化**。
|
||||
|
||||
## 总体架构决策
|
||||
|
||||
1. **地基 = 逐间隙断行许可(breaks-allowed)+ 标点独立成盒**。
|
||||
禁则从"吞噬式附着"迁移为 DP 层的断点禁止;所有后续特性(NBSP、
|
||||
no-break 区间、行内 verbatim 原子、标点类别)都是这套机制的实例。
|
||||
2. **Emacs 显示引擎约束(已确证)**:无法缩减字形 advance(无负宽
|
||||
display)→ CLREQ 行中标点挤压不可渲染;行首/行尾挤压视觉上等价于
|
||||
"悬挂"(protrusion)→ P1-1 + P2-4 + P2-6 统一为**边缘突出机制**,
|
||||
按字符类配比率(可扩展到拉丁连字符突出 = microtype)。
|
||||
3. ragged-right/left/center:DP 侧 = 刚性 glue(stretch/shrink 数组置零)
|
||||
+ 每行额外伸展量 R(badness 以 R 为 flexibility);渲染侧分派剩余量
|
||||
(右/左/对半)。C 只需 +1 标量。
|
||||
4. parshape/首行缩进:每行宽依赖行号 → 复用 looseness 的 2D DP,
|
||||
elisp-only(C 自动旁路,同 looseness 先例)。
|
||||
5. verbatim:段落级豁免(region 层谓词/属性)+ 行内原子
|
||||
(ekp-no-break 属性 → 禁断点 + 刚性 glue + 禁断词)。
|
||||
|
||||
## 关键实现事实(读码结论)
|
||||
|
||||
- tokenizer 附着逻辑在 ekp-utils.el `ekp--handle-cjk-char/latin-char`
|
||||
(开放标点 hold-and-prepend;闭合标点 append-to-prev)。
|
||||
**已知老 bug**:连续闭合标点(字。」)第二个独立成盒且断点未禁止 →
|
||||
」可出现行首;开放标点跨空格 hold 还会导致盒序与原文顺序不一致。
|
||||
迁移后两者都根治。
|
||||
- `ekp--str-type` 返回 space/latin/cjk/cjk-punct → 拆成 cjk-open
|
||||
(opening-punct-p:general-category Ps/Pi)/ cjk-close(fw-punct-p
|
||||
且非 open)。“” 特例保持 'cjk。
|
||||
- `ekp--glue-type` 新矩阵(保持旧拓扑等价):space→nws;
|
||||
before=open→nws(原盒内);after=close→nws(原盒内;close-close
|
||||
从 cws 改为 nws,属有意修正);latin-latin→lws;cjk-cjk→cws;
|
||||
cjk/latin 混→mws;其余含标点→cws。
|
||||
- breaks-allowed 规则:`allowed[k] = !(tail(box[k-1])=open || head(box[k])=close)`,
|
||||
k∈[1,n-1];k=n(段末)恒可。存 bool-vector(elisp DP 用)+
|
||||
forbidden-positions int 向量(C 打包用,稀疏,仿 hyphen-positions)。
|
||||
- DP 改动(elisp `ekp--dp-run-1d` + C `dp_process_position` 镜像):
|
||||
候选 k 需 allowed;不 allowed 时**不 throw**继续延伸;
|
||||
紧急兜底从 single-box 推广为 atomic-run(i 到 k 间无允许断点);
|
||||
多盒紧急行需记录 gaps 计数(渲染 normal 路径 clamp ≥0 自然溢出)。
|
||||
- C 桥:`ekp-c-break-with-arrays` 11→12 参(forbidden-positions),
|
||||
batch 向量同步;`ekp-c-set-penalties` 后续 ragged 加 extra-stretch
|
||||
标量;protrusion 再加两数组(head/tail protrude px)。每次 API 变
|
||||
动 bump EKP_VERSION_MINOR + `ekp-c-module-required-version`。
|
||||
- 隐性收益:「Hello / Hello」 之前整盒无法匹配断词正则(左右标点类
|
||||
不含 CJK 引号)→ 拆盒后可正常断词。
|
||||
- 测试影响:tests/ekp-tests.el 里 split-* 结构测试要改为新盒契约;
|
||||
新增行为级禁则测试(任意宽度:行首无 close、行尾无 open、
|
||||
字。」不拆)。fuzz 断言与引擎无关,应保持 0 失败。
|
||||
|
||||
## 阶段与提交计划(全部完成 2026-07-26)
|
||||
|
||||
- [x] A 地基 64eb2f3:标点成盒 + breaks-allowed + DP/C 1.2;顺带修复
|
||||
连续闭合标点行首漏洞、open-punct 跨空格盒序错乱、「Hello 断词失效;
|
||||
半角标点禁则(纯标点盒判定)
|
||||
- [x] B ea96a6d:ekp-no-break 属性(刚性原子/禁断词)、NBSP/NNBSP/
|
||||
FIGURE SPACE/WJ/ZWNBSP、命令 ×2;零 C 改动
|
||||
- [x] C 57a3abe:ekp-alignment 四模式 + ekp-ragged-stretch-pixel;
|
||||
C 1.3(set-penalties 第 7 参 extra-stretch,缺省归零)
|
||||
- [x] D f6aa64b:ekp-protrusion 右缘悬挂(cjk-close/latin-close/hyphen
|
||||
比率);DP/渲染/C 重建三处 lw=width+release 同步;C 1.4
|
||||
(break-with-arrays 14 参);region 预留 protrusion-reserve;
|
||||
仅右缘(左缘无法渲染,文档已注明)
|
||||
- [x] E 720b1cd:ekp-parshape + ekp-first-line-indent(t=2em 按段落
|
||||
CJK 字体);loose 2D 每行宽;C 旁路
|
||||
- [x] F 4d9a018:ekp-verbatim 段落豁免 + ekp-region-skip-faces +
|
||||
buffer-local skip-predicate;行内原子沿用 ekp-no-break;核心零改动
|
||||
- [x] G:readme×2 排版特性/verbatim 章节、DEVELOPER×2 §5.1;GUI 目检
|
||||
(悬挂+缩进+verbatim+auto-mode 齐行/ragged 两态截图确认)
|
||||
|
||||
最终状态:66 ERT 全绿,fuzz 300/300(每阶段跑),C 模块 1.4 两引擎
|
||||
逐字节一致。行中挤压不可渲染(Emacs 无负宽 display)= 已知边界。
|
||||
|
||||
## 验证清单(每阶段)
|
||||
|
||||
byte-compile 零警告(error-on-warn)→ 47+ ERT → C 重建 + parity →
|
||||
fuzz 300 → 提交。改 ekp_c/ 后必须 make clean && make。
|
||||
Emacs: /Applications/Emacs.app/Contents/MacOS/Emacs
|
||||
144
AGENTS.md
144
AGENTS.md
@ -1,144 +0,0 @@
|
||||
# 核心协议：意图识别（强制执行）
|
||||
|
||||
在处理任何请求之前，你必须先识别用户的意图并遵循相应的协议。
|
||||
|
||||
## 1. 🌱 启动 / 立项 / 模糊想法
|
||||
**触发条件**：用户想要开启新项目、新阶段，或者只有一个模糊的想法。
|
||||
**行动**：
|
||||
1. **扫描**：读取 `.phrase/modules/pr_faq.md` 的 YAML 元数据以确认匹配。
|
||||
2. **加载**：仅当匹配成功时，完整读取该文件内容。
|
||||
3. **执行**：扮演“严格的产品经理”角色。进行访谈以起草亚马逊风格的 PR/FAQ。
|
||||
4. **约束**：在 PR/FAQ 最终确定之前，禁止开始编写代码或拆解任务。
|
||||
|
||||
## 2. 🔨 编码 / 重构 / 审查
|
||||
**触发条件**：用户请求代码实现、Bug 修复、重构或代码审查。
|
||||
**行动**：
|
||||
1. **扫描**：读取 `.phrase/modules/linus_coding.md` 的 YAML 元数据以确认匹配。
|
||||
2. **加载**：仅当匹配成功时，完整读取该文件内容。
|
||||
3. **执行**：扮演“Linus Torvalds”角色。
|
||||
4. **约束**：在编码前和编码过程中，严格执行“5 层思考模型”和“好品味”判断。
|
||||
|
||||
## 3. ✍️ 文案 / 营销 / 文档
|
||||
**触发条件**：用户需要撰写 README、发布说明、产品介绍或营销文案。
|
||||
**行动**：
|
||||
1. **扫描**：读取 `.phrase/modules/copywriting.md` 的 YAML 元数据以确认匹配。
|
||||
2. **加载**：仅当匹配成功时，完整读取该文件内容。
|
||||
3. **执行**：扮演“转化率文案专家”角色。
|
||||
4. **约束**：遵循“结论先行”、“降低成本”、“可感知的具体”等 10 大原则。
|
||||
|
||||
## 4. 🌐 浏览器 / 网页自动化 / 爬虫
|
||||
**触发条件**：用户需要访问网页、抓取数据、截图、测试 Web UI 或填写表单。
|
||||
**行动**：
|
||||
1. **扫描**：读取 `.phrase/modules/agent-browser.md` 的 YAML 元数据以确认匹配。
|
||||
2. **检查**：确保环境中已安装 `agent-browser` 依赖。
|
||||
3. **加载**：仅当匹配成功且依赖满足时，完整读取该文件内容。
|
||||
4. **执行**：使用 CLI 工具进行浏览器自动化操作。
|
||||
|
||||
## 5. 📋 任务执行（默认）
|
||||
**触发条件**：用户想要执行一个具体的、已定义的任务。
|
||||
**行动**：遵循下方的“文档驱动开发”工作流。
|
||||
|
||||
---
|
||||
|
||||
“文档驱动开发（Doc-Driven Development）”：先锁定文档 → 拆 `taskNNN` → 实现与验证 → 回写文档。
|
||||
|
||||
---
|
||||
|
||||
## 0. 原则（按优先级）
|
||||
- 仓库既有规范 > 本文；冲突时按 `README`/`STYLEGUIDE` 等执行，并在 `issue_*`/`change_*` 记录取舍。
|
||||
- 文档为事实来源：需求、交互、接口只能来自 `spec/plan/tech-refer/adr`。
|
||||
- 单次仅处理一个原子任务；所有改动可追溯到 `taskNNN` 与其依据（`spec`/`issue`/`adr`）。
|
||||
- 每个 `taskNNN` 必须说明验证方式（测试或手动步骤）。
|
||||
- 实现完成必须回写：`task_*`、`change_*`，必要时更新 `spec_*`/`issue_*`/`adr_*`。
|
||||
|
||||
---
|
||||
|
||||
## 1. 仓库结构与文档
|
||||
- 代码根：`App/`, `Core/`, `UI/`, `Shared/`, `Tests/`, `Assets/`, `Samples/`, `Schemas/`, `StackWM-Bridging-Header.h`。保持分层清晰，`Tests/` 镜像核心模块。
|
||||
- 文档根：`.phrase/`
|
||||
- 阶段：`.phrase/phases/phase-<purpose>-<YYYYMMDD>/`
|
||||
- 全局索引：`.phrase/docs/`
|
||||
- `Docs/` 为外部文档，可继续独立存放。
|
||||
|
||||
---
|
||||
|
||||
## 2. Phase 工作流
|
||||
1. **Phase Gate**（仅当用户明确开启新阶段）：在新 `phase-*` 目录创建最小集 `spec_*`, `plan_*`, `task_*`, 视需求补 `tech-refer_*`/`adr_*`，`issue_*` 可后置。
|
||||
2. **In-Phase Loop**（默认）：
|
||||
- 新需求 → 更新当前 `plan_*` → 拆 `taskNNN`。
|
||||
- 实现 → 在 `task_*` 中新增/更新并执行对应任务。
|
||||
- Bug → 在 `.phrase/docs/ISSUES.md` 登记 `issueNNN`，在 phase 写详情，再拆 `taskNNN`。
|
||||
- 不可逆决策 → 先写 `adr_*` 或在 `tech-refer_*` 增 “Decision”。
|
||||
3. **Task 闭环**：完成后需
|
||||
1) 将 `task_*` 条目标记 `[x]`
|
||||
2) 在 phase `change_*` 记录条目，并于 `.phrase/docs/CHANGE.md` 加索引
|
||||
3) 若影响交互，更新对应 `spec_*`
|
||||
4) 若解决问题，更新 `ISSUES.md` 和 issue 详情（含验证结论）
|
||||
|
||||
当目标与当前 phase purpose 明显不同、需要独立里程碑或架构大重构时，可建议开启新 phase，但需用户确认。
|
||||
|
||||
### Phase 生命周期
|
||||
- 开启阶段：在 `.phrase/phases/phase-<purpose>-<date>/` 下创建 `spec/plan/task/...`。
|
||||
- 阶段完结：用户确认后，将整个目录重命名为 `DONE-phase-<purpose>-<date>/`，同时把主要文档也按规则改为 `DONE-PLAN-*`、`DONE-TASK-*` 等，确保一眼可见结项状态。
|
||||
|
||||
---
|
||||
|
||||
## 3. Task / Issue 规范
|
||||
- `taskNNN` 为三位递增 ID（`task001` 起），不可重排或复用；拆分/合并需创建新 ID 并在原任务注明流向。
|
||||
- 任何对 `task_*` 的增删改/勾选都要在当前 phase `change_*` 记录一次，可批量合并但必须可追溯。
|
||||
- 原子任务标准：一次工作会话可完成、产出可观察、可独立验证，既不过细也不过粗。
|
||||
- Issue：
|
||||
- 全局索引：`.phrase/docs/ISSUES.md` 用 `issueNNN [ ]/[x]` 并链接 phase 详情。
|
||||
- 详情文件 `issue_<purpose>_<YYYYMMDD>.md` 需含环境、复现、调查、根因、修复、验证、关联的 `taskNNN`/提交。
|
||||
- 用户可感知问题需在标记 `[x]` 前获得确认，并记录 `Resolved At/By/Commit`。
|
||||
|
||||
---
|
||||
|
||||
## 4. Build / Test / Dev
|
||||
- 首选仓库入口：若提供 Makefile、GitHub Actions、或 scripts/，优先使用。
|
||||
- windows系统下 emacs 路径: "C:\Users\26289\Apps\emacs-30.2\emacs-30.2\bin"
|
||||
- 常见 Elisp 验证方式：
|
||||
- 运行 ERT 测试：emacs -Q --batch -L . -l <test-file> -f ert-run-tests-batch-and-exit
|
||||
- 交互手动验证：emacs -Q -L . -l <pkg>.el 后在 UI 中 M-x 执行命令
|
||||
- 可选：lint/格式（按仓库约定），例如 package-lint、checkdoc、byte-compile（若项目采用）。
|
||||
- 测试用例全部写在根目录的 tests/ 目录下
|
||||
|
||||
---
|
||||
|
||||
## 5. 编码与验证
|
||||
- 遵循仓库已有编码规范（缩进、命名、lexical-binding 等）。
|
||||
- 明确支持的 Emacs 版本范围；涉及 API 差异时要写清楚 fallback 或条件分支策略。
|
||||
- 尽量保持改动最小化：除非任务是“清理”，否则避免批量格式化与无关重排。
|
||||
- 关键路径加可诊断日志（遵循项目 logging 方案）。
|
||||
- 测试优先覆盖核心逻辑；UI/系统胶水可提供手动验证步骤。测试必须确定性，必要时注入依赖或 mock。
|
||||
|
||||
---
|
||||
|
||||
## 6. 文档更新与 Changelog
|
||||
- `change_*`：phase 内的真实变更记录；每个完成的 `taskNNN` 至少一条，包含日期、文件/路径、Add|Modify|Delete、受影响函数、行为/风险说明，按时间倒序。
|
||||
- `.phrase/docs/CHANGE.md`：仅索引与摘要，指向对应 phase `change_*` 条目；可按工作会话批量更新。
|
||||
- `spec_*`/`plan_*`/`tech-refer_*`/`adr_*`/`issue_*` 均需随变更回写（增量即可），保持单一事实来源。
|
||||
|
||||
---
|
||||
|
||||
## 7. 提交、PR 与安全
|
||||
- 默认使用 Conventional Commits（`feat:`, `fix:`, `docs:`, `test:`, `chore:` 等），一份提交聚焦单个 `taskNNN`。
|
||||
- PR 描述需列出关联的 `taskNNN`/`issueNNN`、动机、行为变化、验证方式、风险/回滚方案，并在 UI 变化时附截图/GIF。
|
||||
- 禁止提交密钥、token、证书、真实用户数据；涉及权限/配置的任务，需在 `spec_*` 和 `tech-refer_*` 清楚描述失败反馈、API 边界与排查方式。
|
||||
|
||||
---
|
||||
|
||||
## 8. 模板速览
|
||||
- `spec`: Summary / Goals & Non-goals / User Flows（操作→反馈→回退）/ Edge Cases / Acceptance Criteria
|
||||
- `plan`: Milestones / Scope / Priorities / Risks & Dependencies /（可选）Rollback
|
||||
- `tech-refer`: Options / Proposed Approach / Interfaces & APIs / Trade-offs / Risks & Mitigations
|
||||
- `task`: `task001 [ ] 产出 + 验证方式 + 影响范围`
|
||||
- `issue`: `issueNNN [ ] Summary + Environment + Repro + Expected vs Actual + Investigation + Fix + Verification + User Confirmation + Resolved At/By/Commit`
|
||||
- `adr`: Context / Decision / Alternatives / Consequences / Rollback
|
||||
|
||||
---
|
||||
|
||||
## 9. 协作表达提示
|
||||
- 解释方案时优先描述用户操作（快捷键/鼠标/命令）、可见反馈、撤销/失败路径、边界情况。
|
||||
- 引用文档时用“文件名 + 小节”口语化说明，不逐字背诵。
|
||||
- 提供可选方案时说明它们属于当前还是后续里程碑，帮助用户决策。
|
||||
Loading…
Reference in New Issue
Block a user