openclacky 1.1.6 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: d07cc1b558deca4a0bcbbd49133b1e75541437e576811fff6848ea205a1df9e2
-  data.tar.gz: 547e9b2215f53f41902fdfd5f03c99e0f3fd1d532967279c9eb83f62a57d0a0a
+  metadata.gz: e470c0165e741ffd7827e204f2c12dac2e20fe71f1a48431e991558edf3a501c
+  data.tar.gz: be96ec9301fa064406f8bb7e01182406f295899b75c319c1410891d9feaa2925
 SHA512:
-  metadata.gz: 642a482e321f6b4c178143bf7a18e296fd7dcab5e4e10b8ac00676a007e54e972a5bb9ec036932e609e759ed4c946c2bf9d772ed91a15e9561e0c4b68c6b6a0b
-  data.tar.gz: cdd52c0b1d081a9a1931b4ed96d88e780497b44180a37150bce2c1b7d352051c8cf9cf5d973a851665ed9eef5c1e6ce572deb829a41e41ca3f7b2f8791e62c9f
+  metadata.gz: c2f14deab190852f14139556115888daf8cabac65a49274732d67f05c8e20d942ddb70a009c5fd5c970e9af97b3ec4b9cbe5292392b8c90c838df9c2f1c790f9
+  data.tar.gz: f9afcded8e63a1b2aad78b254ce70c5eddc8554cf1390d08a71ef334a1ecd260ad0e242cc97952eeb5aeb767d9b02443514dccef44548f466f58cff0186c6242

data/CHANGELOG.md

@@ -5,6 +5,43 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [1.2.0] - 2026-05-24
+
+### Added
+- MCP (Model Context Protocol) support with HTTP server transport
+- MCP management skill for adding, listing, probing, and reconfiguring MCP servers
+- Settings panel restructure with new "UI" and "About" tabs
+- Advanced settings toggles for compression, prompt caching, and memory update
+- Session recycle bin with soft-delete, restore, and bulk-empty operations (#172)
+- Billing system with USD/CNY currency settings (#166)
+- Configurable default working directory (#170)
+- Model ID select for switching between configured model IDs
+- Sequential image naming with upload order guarantee in Web UI (#188)
+- Browser link tips in agent output
+- Fallback URL support for model providers
+- ROADMAP.md outlining four focus areas
+
+### Improved
+- Browser tool reliability and ergonomics
+- Idle compression interval increased to 314s for fewer interruptions
+- Removed dead WeChat split_message and markdown_to_plain code paths (#187)
+
+### Fixed
+- Brand setting persistence
+- Interactive feedback card now restored during history replay (C-5599) (#190)
+- Model switcher disabled while agent is responding (C-5559) (#189)
+- Stale function call no longer breaks interrupt handling
+- Trash tool now supports directory deletion (#173)
+- Command suggestions dropdown scrolling (#157)
+- Comprehensive mobile Web UI fixes (#165)
+- WSL_UTF8=1 vs OutputEncoding=Unicode conflict in Test-UbuntuInstalled (#164)
+- USR1 hot-reload session info drop bug (#142)
+
+### More
+- DeepSeek price update
+- Contributors list and contributing readme
+- Session translation polish
+
 ## [1.1.6] - 2026-05-22
 
 ### Added

data/CODE_OF_CONDUCT.md

@@ -60,7 +60,7 @@ representative at an online or offline event.
 
 Instances of abusive, harassing, or otherwise unacceptable behavior may be
 reported to the community leaders responsible for enforcement at
-[INSERT CONTACT METHOD].
+opening an issue at https://github.com/clacky-ai/open-clacky/issues.
 All complaints will be reviewed and investigated promptly and fairly.
 
 All community leaders are obligated to respect the privacy and security of the

data/CONTRIBUTING.md

@@ -0,0 +1,92 @@
+# Contributing to OpenClacky
+
+Thanks for taking the time to contribute. Every PR will be reviewed. We evaluate
+each contribution along three dimensions:
+
+1. **Value of the need** — is this useful, and to whom?
+2. **Architectural impact** — does it fit the existing design?
+3. **Code standards** — does it meet our quality bar?
+
+Read the sections below before opening a PR. If your contribution clearly
+delivers outsized value, the rules here can bend — see [Exceptions](#exceptions).
+
+---
+
+## 1. Architecture First
+
+Improvements built on top of the existing, stable architecture are accepted
+quickly. By "stable architecture" we mean a change that:
+
+- Solves the need with the **smallest possible diff**.
+- **Adds no new configuration knobs** unless strictly required.
+- **Adds no new dependencies** unless strictly required (see also §3).
+- **Respects the existing design intent** — same layering, same abstractions,
+  same naming conventions.
+- Ideally **simplifies** the architecture rather than expanding it.
+
+PRs that introduce parallel mechanisms, speculative abstractions, or "just in
+case" flexibility will be sent back for trimming.
+
+## 2. Needs Should Be Shared and Side-Effect-Free
+
+We prefer changes that benefit **most users** and have **no side effects** on
+others.
+
+- **Common needs** (broadly applicable, opt-in by nature, isolated blast
+  radius) → fast track.
+- **Niche needs** (valuable to a few, but with potential to affect others'
+  workflows, performance, or defaults) → reviewed more cautiously. Expect
+  questions about scope, defaults, and rollout.
+
+If your change alters existing default behavior, call it out explicitly in the
+PR description.
+
+## 3. Code Standards
+
+### Tests
+
+- All tests **must pass** before a PR can be merged.
+- **Coverage must not drop.** New code needs new tests.
+
+### Commits & PRs
+
+- **Write commit messages and PR titles/descriptions in English.** This applies
+  to everyone, regardless of working language.
+- Keep commits focused; squash noise before requesting review.
+- PR descriptions should briefly state: what, why, and any user-visible impact.
+
+### Built with OpenClacky
+
+- PRs **authored using OpenClacky itself** are prioritized for review and
+  merge. Mention it in the PR description if applicable. We dogfood our own
+  tool.
+
+### Dependencies
+
+- **Avoid adding new libraries.** Prefer the standard library, existing
+  dependencies, or a few lines of code over pulling in another gem/package.
+- If a new dependency is genuinely necessary, justify it in the PR description:
+  why this library, why not write it ourselves, license, maintenance status.
+
+### Style
+
+- Follow the conventions already present in the file you're editing.
+- See each sub-project's `.clackyrules` for project-specific rules
+  (`openclacky/`, `platform/`, `installer/`).
+
+---
+
+## Exceptions
+
+Rules exist to keep the project healthy, not to block valuable work. For
+contributions that deliver **substantial, clear value**, the standards above
+can be relaxed at the maintainers' discretion. When in doubt, open an issue or
+draft PR first to discuss the trade-offs.
+
+---
+
+## Code of Conduct
+
+Participation in this project is governed by the
+[Code of Conduct](./CODE_OF_CONDUCT.md). By contributing, you agree to uphold
+it.

data/README.md

@@ -10,6 +10,8 @@
   <a href="README.md">English</a> · <a href="README_CN.md">简体中文</a>
 </p>
 
+> Contributing? Read **[CONTRIBUTING.md](./CONTRIBUTING.md)** before opening a PR.
+
 **The most Token-efficient open-source AI Agent.**
 
 OpenClacky matches Claude Code on capability at comparable cost, and saves significantly against other open-source agents (~50% vs OpenClaw, ~3× cheaper than Hermes). 100% open source (MIT), BYOK with any OpenAI-compatible model, built on two years of Agentic R&D and harness engineering.
@@ -184,6 +186,14 @@ bin/clacky
 - **16 core tools** — minimal by design
 - **Backed by** MiraclePlus · ZhenFund · Sequoia China · Hillhouse Capital
 
+## Contributors
+
+Every line of code, bug report, and thoughtful review matters. Thank you for making OpenClacky better.
+
+<a href="https://github.com/clacky-ai/openclacky/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=clacky-ai/openclacky" />
+</a>
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/clacky-ai/openclacky. Contributors are expected to adhere to the [code of conduct](https://github.com/clacky-ai/openclacky/blob/main/CODE_OF_CONDUCT.md).

data/README_CN.md

@@ -6,6 +6,8 @@
 [![Downloads](https://img.shields.io/gem/dt/openclacky?label=downloads&style=flat-square&color=brightgreen)](https://rubygems.org/gems/openclacky)
 [![License](https://img.shields.io/badge/license-MIT-lightgrey?style=flat-square)](LICENSE.txt)
 
+> 想贡献代码？提 PR 前请先读 **[CONTRIBUTING.md](./CONTRIBUTING.md)**。
+
 **最省 Token 的开源 AI Agent。**
 
 OpenClacky 在任务能力上对齐 Claude Code，成本相当，同时相比其他开源 Agent 有显著优势（约节省 50% vs OpenClaw，约便宜 3× vs Hermes）。100% 开源（MIT），支持 BYOK 接入任意 OpenAI 兼容模型，背后是两年 Agentic 研发与 Harness 工程积累。
@@ -189,6 +191,14 @@ bin/clacky
 - [我把 AI 账单从 30 美金打到 5 美金](https://mp.weixin.qq.com/s/BDhE0y8xbX0ea3vLlV37Ig)
 - [100% Cache 命中的 Harness 怎么设计：一个开源 AI Agent 的 7 个工程决策](https://mp.weixin.qq.com/s/Rc1xk0Qw168D4Y07kkBiGQ)
 
+## 贡献者
+
+每一行代码、每一个 Bug 报告、每一次认真的 Review，都让 OpenClacky 变得更好。感谢你们！
+
+<a href="https://github.com/clacky-ai/openclacky/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=clacky-ai/openclacky" />
+</a>
+
 ## 参与贡献
 
 欢迎在 GitHub 提交 Bug 报告和 Pull Request：https://github.com/clacky-ai/openclacky 。参与贡献者须遵守[行为准则](https://github.com/clacky-ai/openclacky/blob/main/CODE_OF_CONDUCT.md)。

data/ROADMAP.md

@@ -0,0 +1,29 @@
+# Roadmap
+
+We're currently focused on four areas. If you'd like to contribute, start here.
+
+## 1. Zero-Extra-Token MCP Integration
+
+Connect OpenClacky to the MCP (Model Context Protocol) ecosystem — plug-and-play MCP Server support, with protocol-level token overhead minimized via caching and compression strategies.
+
+## 2. Plugin System
+
+Design a plugin architecture that lets the community develop, publish, and install plugins without touching core code. Think VS Code Extension-like developer experience.
+
+## 3. Skill UI Extension
+
+Provide visual configuration and interactive extension capabilities for Skills, lowering the barrier to creating and customizing Skills.
+
+## 4. Image & Video Model Support
+
+Native support for image and video generation models (DALL·E, Midjourney, Sora, etc.), enabling agents to generate and orchestrate multimedia content directly in conversations.
+
+---
+
+## How to Contribute
+
+Each direction breaks down into specific tasks tracked as [Issues](https://github.com/clacky-ai/openclacky/issues), labeled with `enhancement`.
+
+New to the project? Start with a [`good first issue`](https://github.com/clacky-ai/openclacky/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22).
+
+Read [CONTRIBUTING.md](./CONTRIBUTING.md) before opening a PR.

data/docs/billing-system.md

@@ -0,0 +1,340 @@
+# Billing System
+
+## Overview
+
+The Billing System provides persistent tracking of API usage and costs across all
+sessions. It records every LLM API call with token counts and calculated costs,
+storing them in monthly JSONL files for easy querying and analysis.
+
+## Design Principles
+
+- **Non-blocking** — Billing persistence is fire-and-forget; failures never interrupt agent flow
+- **Minimal footprint** — JSONL format, one file per month, no database dependency
+- **Privacy-first** — Data stored locally in `~/.clacky/billing/`, never uploaded
+- **Accurate costing** — Uses the same `ModelPricing` module as real-time display
+
+---
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                         Agent                                   │
+│  CostTracker module                                             │
+│    └── track_cost()                                             │
+│          ├── Calculate cost (ModelPricing)                      │
+│          ├── Update UI (real-time)                              │
+│          └── persist_billing_record() ──────┐                   │
+└─────────────────────────────────────────────┼───────────────────┘
+                                              │
+                                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Billing Module                               │
+│  lib/clacky/billing/                                            │
+│    ├── billing_record.rb   (data structure)                     │
+│    └── billing_store.rb    (JSONL persistence)                  │
+└─────────────────────────────────────────────────────────────────┘
+                                              │
+                                              ▼
+┌─────────────────────────────────────────────────────────────────┐
+│                    Storage                                      │
+│  ~/.clacky/billing/                                             │
+│    ├── 2026-05.jsonl                                            │
+│    ├── 2026-04.jsonl                                            │
+│    └── ...                                                      │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Components
+
+### BillingRecord (`lib/clacky/billing/billing_record.rb`)
+
+A Struct representing a single API call:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | String | UUID, auto-generated |
+| `session_id` | String | Associated session |
+| `timestamp` | Time | When the call was made |
+| `model` | String | Model name (e.g., "claude-sonnet-4.5") |
+| `prompt_tokens` | Integer | Input tokens |
+| `completion_tokens` | Integer | Output tokens |
+| `cache_read_tokens` | Integer | Tokens read from cache |
+| `cache_write_tokens` | Integer | Tokens written to cache |
+| `cost_usd` | Float | Calculated cost in USD |
+| `cost_source` | Symbol | `:api`, `:price`, or `:estimated` |
+
+### BillingStore (`lib/clacky/billing/billing_store.rb`)
+
+Handles persistence and querying:
+
+```ruby
+store = Clacky::Billing::BillingStore.new
+
+# Append a record
+store.append(record)
+
+# Query with filters
+records = store.query(from: 1.week.ago, model: "claude-sonnet-4.5", limit: 100)
+
+# Get summary statistics
+summary = store.summary(period: :month)
+# => { total_cost: 12.34, total_tokens: 500000, by_model: {...}, ... }
+
+# Daily breakdown for charts
+daily = store.daily_breakdown(days: 30)
+# => [{ date: "2026-05-01", cost: 1.23, tokens: 50000, requests: 42 }, ...]
+```
+
+---
+
+## Storage Format
+
+Records are stored as JSON Lines (one JSON object per line):
+
+```jsonl
+{"id":"abc123","session_id":"def456","timestamp":"2026-05-22T15:30:00+08:00","model":"claude-sonnet-4.5","prompt_tokens":1500,"completion_tokens":500,"cache_read_tokens":1000,"cache_write_tokens":0,"cost_usd":0.0045,"cost_source":"price"}
+{"id":"abc124","session_id":"def456","timestamp":"2026-05-22T15:31:00+08:00","model":"claude-sonnet-4.5","prompt_tokens":2000,"completion_tokens":800,"cache_read_tokens":1500,"cache_write_tokens":0,"cost_usd":0.0052,"cost_source":"price"}
+```
+
+**Why JSONL?**
+- Append-only writes (no file locking needed)
+- Easy to parse line-by-line (memory efficient)
+- Human-readable for debugging
+- Simple monthly rotation
+
+---
+
+## API Endpoints
+
+### GET /api/billing/summary
+
+Returns aggregated statistics for a time period.
+
+**Query Parameters:**
+- `period` — `day`, `week`, `month`, `year`, or `all` (default: `month`)
+
+**Response:**
+```json
+{
+  "period": "month",
+  "from": "2026-05-01T00:00:00+08:00",
+  "to": "2026-05-22T15:30:00+08:00",
+  "total_cost": 12.3456,
+  "total_tokens": 500000,
+  "prompt_tokens": 350000,
+  "completion_tokens": 150000,
+  "cache_read_tokens": 200000,
+  "cache_write_tokens": 50000,
+  "by_model": {
+    "claude-sonnet-4.5": { "cost": 10.00, "requests": 100 },
+    "deepseek-v4-flash": { "cost": 2.34, "requests": 50 }
+  },
+  "by_day": {
+    "2026-05-22": 1.23,
+    "2026-05-21": 2.34
+  },
+  "record_count": 150
+}
+```
+
+### GET /api/billing/daily
+
+Returns daily cost breakdown for charting.
+
+**Query Parameters:**
+- `days` — Number of days (default: 30, max: 90)
+
+**Response:**
+```json
+{
+  "days": [
+    { "date": "2026-05-22", "cost": 1.2345, "tokens": 50000, "requests": 42 },
+    { "date": "2026-05-21", "cost": 2.3456, "tokens": 80000, "requests": 65 }
+  ]
+}
+```
+
+### GET /api/billing/records
+
+Returns raw billing records.
+
+**Query Parameters:**
+- `limit` — Max records (default: 100, max: 500)
+- `model` — Filter by model name
+- `session_id` — Filter by session ID
+
+**Response:**
+```json
+{
+  "records": [
+    { "id": "...", "timestamp": "...", "model": "...", "cost_usd": 0.01, ... }
+  ],
+  "count": 100
+}
+```
+
+---
+
+## CLI Command
+
+```bash
+# Show current month's billing
+clacky billing
+
+# Show specific period
+clacky billing --period week
+clacky billing --period day
+clacky billing --period all
+
+# Output as JSON (for scripting)
+clacky billing --json
+```
+
+**Sample Output:**
+```
+📊 Billing Summary (month)
+──────────────────────────────────────────────────
+
+  💰 Total Cost:       $12.3456
+  📝 Total Tokens:     500,000
+  📥 Prompt Tokens:    350,000
+  📤 Completion:       150,000
+  🗄️  Cache Read:       200,000
+  📝 Cache Write:      50,000
+  🔢 API Requests:     150
+
+📈 By Model:
+──────────────────────────────────────────────────
+  claude-sonnet-4.5
+    Cost: $10.0000  |  Requests: 100
+  deepseek-v4-flash
+    Cost: $2.3456  |  Requests: 50
+
+📅 Recent Daily Usage:
+──────────────────────────────────────────────────
+  2026-05-22  $1.2345  ████████████
+  2026-05-21  $2.3456  ████████████████████████
+
+──────────────────────────────────────────────────
+  Data stored in: ~/.clacky/billing/
+```
+
+---
+
+## Web UI
+
+The Billing panel is accessible from the sidebar under "My Data":
+
+- **Summary cards** — Total cost, tokens, API requests
+- **Token breakdown** — Prompt, completion, cache read/write
+- **By Model table** — Cost and request count per model
+- **Daily chart** — Visual bar chart of recent usage with detailed tooltips
+- **Period selector** — Filter by day/week/month/year/all
+
+### Daily Chart Tooltips
+
+Hover over any bar in the daily chart to see detailed information:
+- Date and total cost
+- Input tokens (prompt)
+- Output tokens (completion)
+- Cache read tokens with hit rate percentage
+- Cache write tokens
+- Number of API requests
+
+---
+
+## Currency Settings
+
+The Web UI supports multiple currencies for cost display:
+
+| Currency | Symbol | Default Exchange Rate |
+|----------|--------|----------------------|
+| USD | $ | 1.0 (base) |
+| CNY | ¥ | 6.7944 (customizable) |
+
+### Configuration
+
+1. Go to **Settings** page
+2. Find the **Currency** section
+3. Select `$ USD` or `¥ CNY`
+4. When CNY is selected, you can customize the exchange rate
+
+### Custom Exchange Rate
+
+When CNY is selected, an exchange rate input field appears:
+- Default rate: 6.7944 (1 USD = 6.7944 CNY)
+- Enter any positive number to customize
+- Changes take effect immediately
+- Rate is saved to browser localStorage
+
+### Scope
+
+Currency settings apply to:
+- Billing panel (total cost, model costs, daily chart)
+- Session info bar (top cost display)
+- Token usage lines (per-API-call cost)
+- Task completion messages
+
+**Note:** CLI always displays costs in USD (API's native currency).
+
+### Implementation
+
+Currency preference is stored in browser `localStorage`:
+- `clacky-currency`: Currency code ("USD" or "CNY")
+- `clacky-exchange-rate`: Custom exchange rate (number)
+
+```javascript
+// Access currency utilities from Billing module
+Billing.getCurrency()       // "USD" or "CNY"
+Billing.getCurrencySymbol() // "$" or "¥"
+Billing.convertCost(usd)    // Convert USD to selected currency
+Billing.getExchangeRate()   // Get current exchange rate
+```
+
+---
+
+## Integration with CostTracker
+
+The billing system hooks into `Agent::CostTracker#track_cost`:
+
+```ruby
+def track_cost(usage, raw_api_usage: nil)
+  # ... existing cost calculation ...
+  
+  # Persist billing record (skip for subagents to avoid double-counting)
+  unless @is_subagent
+    persist_billing_record(usage, iteration_cost)
+  end
+  
+  token_data
+end
+```
+
+**Key behaviors:**
+- Subagent costs are NOT recorded separately (parent agent merges them)
+- Unknown model costs (nil) are skipped
+- Persistence failures are logged but never raise
+
+---
+
+## Data Retention
+
+- Records are stored indefinitely by default
+- Monthly files can be manually deleted from `~/.clacky/billing/`
+- Future: `BillingStore#cleanup(before: 1.year.ago)` for automated retention
+
+---
+
+## Future Enhancements
+
+- [ ] Export to CSV/JSON
+- [ ] Budget alerts (daily/monthly limits)
+- [ ] Cost comparison across models
+- [ ] Session-level cost breakdown in UI
+- [x] i18n support for billing labels (English/Chinese)
+- [x] Currency settings (USD/CNY)
+- [ ] Dynamic exchange rate updates
+- [ ] More currency options (EUR, JPY, etc.)