diff --git a/CHANGELOG.md b/CHANGELOG.md index e7b927c..efff3ce 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,16 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). ## [Unreleased] +### Changed + +- **The Mintlify docs site is now English-only.** The five hand-maintained translated + locale trees (`ar`, `hi`, `cn`, `zh-CN`, `zh-Hans`) were removed — keeping parallel prose + in sync by hand was the main source of documentation drift. `mintlify/docs.json` now + declares a single `en` language. To bring translations back, enable Mintlify's built-in + AI auto-localization instead of hand-maintaining parallel `.mdx` trees; the setup steps + are documented in `mintlify/README.md`. The English-scoped `checkMintlify` drift guard is + unaffected. + ## [0.27.2] - 2026-07-21 ### Changed diff --git a/mintlify/README.md b/mintlify/README.md index e3cdd05..bc2a8cc 100644 --- a/mintlify/README.md +++ b/mintlify/README.md @@ -54,3 +54,24 @@ handles deploys. The only CI added is an advisory broken-link check file paths relative to this folder, without the `.mdx` extension. - Keep content grounded in the real repo docs — Forge has a "no mock data / metrics must be real" ethos. Do not add invented features or benchmark numbers. + +## Localization + +The site is **English-only**. It previously carried five hand-maintained translations +(`ar`, `hi`, `cn`, `zh-CN`, `zh-Hans`); those trees were removed because keeping parallel +prose in sync by hand was the main source of documentation drift — every English fix had +to be re-applied five times, and any miss left the site lagging the code. + +If translations are wanted again, add them the automated way instead of hand-maintaining +parallel `.mdx` trees: + +- **Mintlify auto-localization** — write English once, list the locale codes under + `navigation.languages` in `docs.json`, and enable AI translation for the deployment in + the Mintlify dashboard. Mintlify generates and refreshes the translated pages; there are + no per-locale files to maintain in this repo. +- **Code→docs Workflow** — configure a Mintlify + [Workflow](https://www.mintlify.com/docs/automations) (dashboard → Automations) so the + site updates from the source repo automatically, rather than drifting until + `forge docs check` catches it. The repo-side guard (`checkMintlify` in + `src/docs_check.js`) stays as a backstop and is scoped to the English pages, so it keeps + working regardless of how many display languages are enabled. diff --git a/mintlify/ar/changelog/overview.mdx b/mintlify/ar/changelog/overview.mdx deleted file mode 100644 index 1459490..0000000 --- a/mintlify/ar/changelog/overview.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "سجل التغييرات: آخر تحديثات وميزات منصة Forge الرسمية" -description: "استعرض أحدث ميزات Forge وتحسيناته، بما في ذلك تحديثات نتائج التحقق العميق متعدد الحالات وبوابات إكمال الجلسات المُطوَّرة حديثاً لضمان الجودة." ---- - - - -## التحديثات - -**`forge verify --deep` أصبح يُبلّغ الآن عن نتيجة رباعية الحالات.** لم يعد -تشغيل الإجماع متعدد العدسات يُختزل إلى نجاح أو فشل ثنائي. سترى إحدى النتائج -`PASS` أو `FAIL` أو `INCOMPLETE` أو `NOT_CONFIGURED`، بحيث لا يمكن لعدسة -متوقفة أو مستودع غير مُهيّأ أن يظهر بصمت على أنه أخضر. فقط `PASS` تُحتسب على -أنها متحقق منها، كما أن `PASS` تتطلب الآن أيضاً أن تكون حالة اختبارات -`forge verify` الأساسية `PASS` — فلا يمكن أبداً لتشغيل عميق أخضر أن يتجاوز -تشغيلاً أساسياً أحمر. - -راجع [أوامر الجودة](/ar/cli/quality) و -[بوابات التحقق](/ar/concepts/verification-gates). - -**بوابة الإكمال تتطلب دليلاً من الاختبارات لتغييرات الكود.** لأي جلسة -مسّت الكود المصدري، لم تعد بوابة إكمال مسار Stop تقبل لقطة `forge handoff` -وحدها. ستحتاج إما إلى ملف اختبار في تغييرات الجلسة أو إلى تشغيل ناجح جديد -لـ `forge verify` مقابل التغييرات الحالية. أما الجلسات الخاصة بالوثائق فقط -أو بالإعدادات فقط أو الجلسات غير البرمجية الأخرى فلا تتأثر. - -عندما تُغلق البوابة الطريق، تبدأ قائمة الإصلاح الآن بـ `forge verify` كي -يُسجَّل الدليل قبل لقطة التسليم. راجع -[الذاكرة عبر الجلسات](/ar/concepts/cross-session-memory). - -**توضيح موقع الـ hooks والحواجز الوقائية.** الـ hooks التلقائية في Forge -خاصة بـ Claude Code تحديداً، وهي — كسائر الإشارات الاستشارية الأخرى — -مُعطَّلة افتراضياً حتى تُفعِّلها صراحةً عبر `FORGE_ENFORCE=1`. الحواجز -الوقائية هنا هي دفاع متعدد الطبقات، وليست صندوقاً أمنياً مُحكماً. لم يتغيّر -شيء في وقت التشغيل؛ فقط جرى ضبط نصوص الوثائق وسطر الأوامر لتُطابق ما تفعله -الأداة فعلياً. راجع [نظرة عامة على CLI](/ar/cli/overview) و -[بوابة ما قبل التنفيذ](/ar/concepts/pre-action-gate). - -## الإصلاحات - -**مُنقِّح الأسرار أصبح يحافظ على الإخراج المُهيكل للأدوات.** الأدوات -المدمجة مثل `Bash` و`Read` و`Grep` تُرجع كائنات مُهيكلة، وكان المُنقِّح -السابق يُحوِّل هذه الاستجابات إلى نصوص — ما كان يعني أن `Claude Code` -يتجاهل عملية إعادة الكتابة بصمت ويبقى الإخراج غير المُنقَّح ظاهراً. أصبح -المُنقِّح الآن يجتاز الاستجابة بشكل تعاودي: تُنظَّف السلاسل النصية في -مكانها، وتحتفظ المصفوفات والكائنات بمفاتيحها وبنيتها، وتمر الأوراق غير -النصية دون تغيير. الاستجابات النصية البسيطة تُنقَّح بشكل مطابق بايت ببايت -لما كان عليه الحال سابقاً، والاستجابة التي لا تحوي ما يستوجب التنقيح لا -تُصدر أي إعادة كتابة على الإطلاق. - -**حالة الخروج مع `FORGE_GUARD_STRICT=1` لم تعد تُبتلَع.** كان الغلاف -الصدفي (shell wrapper) للمُنقِّح يفرض خروجاً نظيفاً، مُخفياً رمز الفشل في -الوضع الصارم عن `Claude Code`، فلا تظهر إشارة `DEGRADED` أبداً. أصبحت -حالة خروج العملية الفرعية الآن تُنقَل من طرف إلى طرف، فتصلك فعلاً تغذية -`stderr` الراجعة الخاصة بالوضع الصارم. لاحظ أن هذا الـ hook يعمل بعد أن -تكون الأداة قد نُفِّذت بالفعل — فالوضع الصارم يجعل تدهور المُنقِّح -مسموعاً وواضحاً، لكن حجب استدعاء قبل تنفيذه هو مهمة -[بوابة ما قبل التنفيذ](/ar/concepts/pre-action-gate). - - diff --git a/mintlify/ar/cli/config.mdx b/mintlify/ar/cli/config.mdx deleted file mode 100644 index 24b14ab..0000000 --- a/mintlify/ar/cli/config.mdx +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: "أوامر Config" -description: "المزوِّدون، والتكلفة، ولوحات المعلومات، والعلامة التجارية، والأطلس، والحزمة، وتكاملات MCP الاختيارية: config وcost وdash وbrand وatlas وstack وreport وtools وintegrations." ---- - -تُغطّي مجموعة Config المزوِّدين، والملاحظة، ورسم الشيفرة، واكتشاف الحزمة. - -## `forge config` - -إعداد المزوِّد — عرض / تبديل / إضافة المزوِّدين، وضبط النموذج الافتراضي. - -```bash -forge config # show current config -forge config switch -forge config add -``` - -## `forge cost` - -الإنفاق الفعلي في اليوم عبر معاملات المراحل المُقاسة. - -```bash -forge cost # real per-day spend -forge cost --stages # measured per-stage cost factors -``` - - - يُبلَّغ عن **المراحل المُقاسة فقط** — المرحلة التي لا أحداث فيها تقول "لا بيانات"، - وليس قيمة افتراضية. - - -## `forge dash` - -لوحة معلومات محلية فوق السجل والقياسات ونصف قطر الانفجار. - -```bash -forge dash # localhost-only (default port 4242) -``` - -## `forge brand` - -طباعة خريطة رموز العلامة التجارية الفعّالة. - -```bash -forge brand -``` - -تُخزَّن العلامة التجارية كرمز واحد (`brand.json`)؛ إعادة التسمية تعديل واحد فقط. - -## `forge atlas` - -بناء/استعلام رسم الشيفرة. - -```bash -forge atlas build [path] # walk the tree → .forge/atlas.json -forge atlas query "what calls Z" -forge atlas has # hallucinated-symbol check -``` - -الأطلس JSON عادي — أي أداة تقرؤه، ولا حاجة إلى MCP. - -## `forge stack` - -اكتشاف حزمة المستودع الفعلية من ملفات البيانات الوصفية. - -```bash -forge stack -``` - -يقرأ `package.json`، و`pyproject.toml`، و`go.mod`، و`Cargo.toml`، و`Gemfile`، -و`composer.json`، و`pom.xml` / `build.gradle`، و`*.csproj`، ويُبلغ عن اللغات، -وأُطر العمل، ومديري الحِزم، وأوامر الاختبار **الفعلية** للمستودع — التي تُغذّي قائمة -تحقق الركيزة. - -## `forge report` - -توليد تقرير HTML ثابت عن حالة Forge للمستودع — السجل والقياسات ونصف قطر الانفجار -مُصيَّرة في ملف مكتفٍ ذاتيًا يمكنك مشاركته أو أرشفته. - -```bash -forge report -``` - -## `forge tools` - -اختَر أداة الترميز الأساسية بالذكاء الاصطناعي لهذا المستودع، ووصِّل مدخلات `.gitignore` -المطابقة، ليتم تجاهل الإعدادات المُولَّدة وقطع `.forge/` تجاهلًا صحيحًا لإعدادك. - -```bash -forge tools -``` - -## `forge integrations` - -خوادم MCP طرف ثالث اختيارية (على سبيل المثال `context7`)، تُدار بلا إتلاف عبر كل -أداة يُصدر Forge إعدادًا لها — Claude Code، وCodex، وCursor، وGemini، وContinue، -وبقيّة الأدوات. - -خوادم MCP الطرف الثالث **غير** مثبّتة افتراضيًا. لا شيء يهبط على القرص إلى أن تُشغّل -`forge integrations add --yes`. - -```bash -forge integrations # list opt-in servers with package + purpose -forge integrations add # dry-run: prints package, network, files it would touch -forge integrations add --yes # apply — write MCP config for every tool -forge integrations add --yes --adopt # also claim a same-name entry you already configured -forge integrations remove # reverse the add — deletes only forge-owned entries -``` - -### ماذا يكتب `add` - -يكتب `add --yes` الخادمَ في إعداد MCP الأصلي لكل أداة من مواصفة قانونية واحدة: - -- `.mcp.json` (Claude Code) -- `.cursor/mcp.json` (Cursor) -- `.gemini/settings.json` (Gemini) -- `.codex/config.toml` — ككتلة `# forge:managed:`، تُحدَّث بمقارنة البايتات -- `.continue/mcpServers/.yaml` — ملف YAML واحد مُعلَّم بعلامة forge لكل خادم مُدار -- وبقيّة الأدوات التي يُصدر Forge إعدادًا لها - -تُسجَّل المجموعة المثبّتة في `.forge/forge.config.json` تحت `mcp.integrations`، فيُعيد -كلُّ `forge sync` لاحق إصدارَ الخوادم نفسها. تُقارن مزامنةُ خطّاف التوقف التلقائي -ملفَّ الإعداد كاملًا بالبايت، فيُكتشف أي تعديل يدوي على ذلك الملف ويُصلَح. - -### دلالات `--adopt` - -إذا كان هناك خادم بالاسم نفسه موجود سلفًا في أحد ملفات إعدادات الأدوات ولم يضعه -Forge هناك، فإن `add` **لا يستبدله**. بل يُبلّغ عن الملف مع تلميح `--adopt`. -أعِد التشغيل بـ `--adopt` للمطالبة بالملكية — يُسجّل Forge المدخل تحت -`mcp.adopted` في `.forge/forge.config.json` وسيُديره من ذلك الحين. - -استخدم `--adopt` عندما تكون قد أعددت خادمًا يدويًا سابقًا وتريد الآن أن يُبقيه Forge -متزامنًا عبر كل الأدوات. - -### `remove` - -يعكس `forge integrations remove ` عمليةَ الإضافة. يحذف فقط المدخلات والكتل -والملفات المملوكة لـ forge — أما الخادم الذي يحمل الاسم نفسه وأعدّه المستخدم (ولم -يُطبَّق عليه `--adopt`) فيُترك كما هو. تشغيل `remove` مرّتين لا أثر له. - -```bash -forge integrations remove context7 -``` - -### `.forge/forge.config.json` - -حالة Forge لكل مستودع — الإعداد الموحّد الذي يحمل أيضًا `primaryTool` و`tools` -و`profile` — تُسجّل التكاملات الاختيارية تحت مفتاحين: - -```json -{ - "mcp": { - "integrations": ["context7"], - "adopted": [] - } -} -``` - -المفاتيح غير المعروفة تعبر الكتابات دون تغيير. لا يُتجاهل الملف المُعطوب بصمت: -تُصدر عمليات القراءة تحذيرًا واحدًا لكل عملية على stderr، ويرفض الكاتبون استبدال -إعداد لا يمكن تحليله بدلًا من الكتابة فوقه بالقيم الافتراضية. diff --git a/mintlify/ar/cli/core.mdx b/mintlify/ar/cli/core.mdx deleted file mode 100644 index f253b62..0000000 --- a/mintlify/ar/cli/core.mdx +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: "أوامر Core" -description: "تهيئة مستودع Forge والحفاظ عليه عبر init وsync وdoctor وcatalog وdocs وupdate — إضافةً إلى ملف السياسة والإعدادات وعلامات إلغاء التثبيت القابل للعكس." ---- - -تُهيّئ مجموعة Core المستودع وتحافظ على صحته. - -## `forge init` - -بناء إعداد هذا المستودع — يُصدر لكل أداة من مصدر مشترك واحد. - -```bash -forge init -``` - -يُصدر `AGENTS.md`، و`CLAUDE.md`، و`.gemini/settings.json`، و`.aider.conf.yml`، والباقي -(إضافةً إلى إعداد خادم MCP لأدوات Roo Code وVS Code)، وقاعدة الدمج الاتحادي في -`.gitattributes` التي يحتاجها السجل. - -كما يدمج `forge init` خطّافات Forge وأذوناتها في ملف `~/.claude/settings.json` -**العام**، لذا يُعلن عن الدمج قبل الكتابة. الدمج عديم الأثر، محميّ بعلامة، ولا يُلغي -مطلقًا مدخلات المستخدم. - -### علامات init - -| العلامة | ماذا تفعل | -| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--profile ` | اختيار ملف السياسة لهذا المستودع. يقبل `minimal` أو `standard` (الافتراضي). قيمة غير صالحة تُجهض قبل أي بناء أو كتابة `.forge/` أو دمج. | -| `--no-settings` | تخطّي دمج ملف `~/.claude/settings.json` العام كليًا — تُكتب فقط الإعدادات الخاصة بالمستودع. | -| `--remove-settings` | عكس دمج إعدادات سابق. تُزال الخطّافات والأذونات وسطر الحالة ذات شكل Forge وعلامة `_forge`؛ تُكتب نسخة احتياطية موسومة بالوقت أولًا، وتُحفظ مدخلاتك. يُستدعى أيضًا من `install.sh --uninstall`. | -| `--settings-only` | دمج الإعدادات العامة فقط — لا يمسّ المستودع. يستخدمه `install.sh` لتوصيل الخطّافات والأذونات. | - -إذا رُفض دمج الإعدادات أو أخفق، يفشل `forge init` بخروج 1 ويكتب السبب إلى stderr بدلًا -من الإبلاغ عن النجاح. - -### ملفات السياسة - -تختار `--profile` مجموعة القواعد التي يُصرّفها `forge sync` إلى إعداد كل أداة الأصلي. -يُدعم ملفان اثنان فقط: - -- **`standard`** (الافتراضي) — الحزمة الكاملة: قواعد الذاكرة المشتركة، وتحليل الأثر، - ومجموعة الخطّافات الحارسة الكاملة. -- **`minimal`** — مجموعة قواعد أخفّ للمستودعات الصغيرة أو تفريعات المساهمين. - -الأسماء الموروثة `web-app` و`backend-service` و`library` و`regulated` أسماء بديلة -مهجورة لـ `standard`. لا تزال تعمل: يُحذّر `forge init` مرة واحدة، ويحفظ `standard`، -وتتزامن الإعدادات الحالية التي تحمل اسمًا موروثًا كما لو كانت standard. على المستودعات -الجديدة استخدام `standard` مباشرةً. أي قيمة أخرى غير صالحة وتُجهض قبل أن يمسّ Forge -المستودع. - -```bash -forge init --profile minimal # leaner ruleset -forge init --no-settings # per-repo only, skip the global merge -forge init --remove-settings # reverse a past global merge -``` - -## `forge sync` - -إعادة تصريف المصدر القانوني إلى ملفات الإعداد الأصلية لكل أداة. - -```bash -forge sync -``` - -عديم الأثر — يعيد كتابة ما تغيّر فقط. شغّله بعد تعديل `source/rules.json` أو -`.forge/rules.json` الخاص بالمستودع. - -## `forge doctor` - -فحص صحة الأدوات المثبتة، والحواجز، ومصادقة MCP، وانحراف الإعدادات. - -```bash -forge doctor -``` - -نجاح/إخفاق عبر الأدوات، والحواجز، وتوصيلات MCP، وانحراف الإعدادات، وحالة التحديث. كل -مسار يفشل بلطف. يطبع صف **نماذج البوّابة** التعيين المحلول `tier → model` عند إعداد -بوّابة مخصّصة. - -## `forge catalog` - -ابدأ من هنا — يعرض كل أداة، وطاقم، وحاجز مع سبب موجز من سطر واحد. - -```bash -forge catalog -``` - -## `forge docs` - -انحراف التوثيق ↔ الشيفرة. - -```bash -forge docs check # registry reconcile — commands, env vars, MCP tools, CHANGELOG -forge docs sync # diff-driven stale-docs sweep -``` - - - يفشل `docs check` في CI عندما تنحرف الأوامر، أو متغيرات البيئة، أو أدوات MCP، أو - CHANGELOG عن الشيفرة. يمسح `docs sync` الفرق ويُبلغ عن UPDATED / STALE / - VERIFIED-UNAFFECTED. - - -## `forge update` - -تحديث ذاتي عبر أنماط التثبيت الثلاثة كلها. - -```bash -forge update # apply the update (git checkout or npm/copy install) -forge update --check # report whether a newer version is available -forge update --to # pin or downgrade to a specific version -``` - -كل مسار يفشل بلطف — دون اتصال أو منبع أو رأس منفصل يُرجَع "غير معروف"، لا خطأ. -`FORGE_NO_UPDATE_CHECK=1` يُسكت إشعار الطبيب. diff --git a/mintlify/ar/cli/memory.mdx b/mintlify/ar/cli/memory.mdx deleted file mode 100644 index bcb41d9..0000000 --- a/mintlify/ar/cli/memory.mdx +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "أوامر Memory" -description: "الذاكرة عبر الجلسات وذاكرة الفريق: cortex وrecall وremember وbrain وledger وreuse وhandoff وdecide — تلتقي جميعها في السجل الحامل للإثبات." ---- - -تُدير مجموعة Memory الذاكرة عبر الجلسات وذاكرة الفريق. تلتقي كلها في السجل الحامل -للإثبات تحت `.forge/ledger/`. راجع -[الذاكرة الحاملة للإثبات](/ar/concepts/proof-carrying-memory) للنموذج. - -## `forge cortex` - -ذاكرة مشروع ذاتية التصحيح — دروس مستنبطة من التصحيحات. - -```bash -forge cortex status # what's been learned -forge cortex why # why a lesson applies here -``` - -## `forge recall` - -إدارة الذاكرة الشخصية عبر الجلسات. - -```bash -forge recall list # facts the recall-load guard injects next session -forge recall add "db port" "Postgres is on 5433 here, not 5432" -forge recall consolidate # summarize (advisory, human-reviewable) -``` - -## `forge remember` - -إضافة حقيقة دائمة وقابلة للحفظ في المستودع إلى ذاكرة المستودع المحمولة. - -```bash -forge remember "" -``` - -## `forge brain` - -عرض أو إعادة بناء فهرس ذاكرة المشروع المحمول. - -```bash -forge brain # show the index -forge brain --rebuild # rebuild it -``` - -## `forge ledger` - -الذاكرة الحاملة للإثبات — مخزن الادعاءات المعنون بمحتواه. - -```bash -forge ledger stats # what the repo knows, by kind and trust level -forge ledger verify # re-check claims are in normal form -forge ledger show # a claim and its evidence -forge ledger blame # who minted it, every oracle outcome, per-author trust -forge ledger query "" # retrieve by relevance -forge ledger ratify # human accept -forge ledger retract # tombstone a claim -forge ledger merge # fold a teammate's ledger in, conflict-free -forge ledger import # back-fill pre-ledger history into the ledger -``` - -أضف `--personal` للحصول على سجل خاص بالمستخدم. - -## `forge reuse` - -مخبأ شيفرة حامل للإثبات — يُقدَّم فقط عندما تظل أدلته صالحة. - -```bash -forge reuse query "" # verified code you already have -forge reuse mint "" --file # add an artifact to the cache -forge reuse stats # cache stats -``` - -## `forge handoff` - -لقطة جلسة محدودة — تُعيد كتابة `.forge/state.md`، وتُحقن في بداية كل جلسة. - -```bash -forge handoff "" --next "" -``` - -## `forge decide` - -سجل قرارات إضافي فقط — إدخالات ADR-lite بصيغة `D-####` في `.forge/decisions.md`. - -```bash -forge decide " — " -forge decide # read the log before re-deciding -``` - -## `forge know` - -توجيه حقيقة إلى موطن تخزينها الصحيح — يقرر ما إذا كانت المعرفة تنتمي إلى -`recall`، أو `remember`/`brain`، أو قرار، أو درس cortex، ويودعها هناك. - -```bash -forge know "" -``` - -## `forge deja` - -بحث عن أعمال سابقة مماثلة — يُظهر الأعمال السابقة في السجل التي تشبه ما توشك على -عمله، لتعيد استخدام الإثبات بدلًا من التوليد من جديد. - -```bash -forge deja "" -``` diff --git a/mintlify/ar/cli/overview.mdx b/mintlify/ar/cli/overview.mdx deleted file mode 100644 index 50e1a74..0000000 --- a/mintlify/ar/cli/overview.mdx +++ /dev/null @@ -1,72 +0,0 @@ ---- -title: "نظرة عامة على CLI" -description: "كل أمر من أوامر forge مُصنَّف حسب المجموعات Core وMemory وSubstrate وQuality وConfig، إضافةً إلى متغيرات البيئة التي تتحكم في التنفيذ والمخرجات." ---- - -يُعرَّف سطح أوامر `forge` كبيانات (`src/commands.js`)، ويتم توفيقه مع التوثيق عبر -`forge docs check`، بحيث لا يستطيع أمر أن يُشحن أو يختفي دون أن يلاحظه التوثيق. تُنظَّم -الأوامر في خمس مجموعات. - - - - التهيئة والصيانة: `init`، و`sync`، و`doctor`، و`catalog`، و`docs`، و`update`. - - - الذاكرة عبر الجلسات وذاكرة الفريق: `cortex`، و`recall`، و`remember`، و`brain`، - و`ledger`، و`reuse`، و`handoff`، و`decide`. - - - بوّابة ما قبل الفعل ومراحلها: `substrate`، و`preflight`، و`route`، و`impact`، - و`scope`، و`context`، و`anchor`، و`diagnose`، و`imagine`، و`lean`. - - - التحقق والسلامة: `verify`، و`scan`، و`spec`، و`taste`، و`uicheck`، و`harden`. - - - المزوِّدون، والتكلفة، ولوحات المعلومات، والعلامة التجارية، والأطلس، والحزمة: - `config`، و`cost`، و`dash`، و`brand`، و`atlas`، و`stack`. - - - -## الاصطلاحات - -- **إرشادي افتراضيًا.** اضبط `FORGE_ENFORCE=1` لتحويل الركيزة إلى حجب صارم على أقوى - الإشارات (طلب فارغ، سياق مطلوب غير قابل للتجميع، نصف قطر انفجار يتجاوز عتبة - 25 ملفًا الافتراضية). -- **صامت افتراضيًا.** العنوان `Forge — …` لكل أمر هو زينة علامة تجارية خلف - `--verbose` / `FORGE_VERBOSE`؛ يُصدر الأمر نتيجته أولًا. -- **مخرَجات ملائمة للأنبوب.** نص عادي عند الأنبوب؛ في الطرفية يضيف ألوان لوحة العلامة - التجارية ومقاييس الثقة. `NO_COLOR` يوقف اللون، `FORCE_COLOR=1` يُفرضه. -- **`--json`** متاح للركيزة ومعظم أوامر التحليل للسكربتات. - -## متغيرات البيئة - -| المتغيّر | الأثر | -| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `FORGE_ENFORCE=1` | تحويل أقوى إشارات الركيزة الإرشادية إلى حجب صارم. | -| `FORGE_GUARD_STRICT=1` | ترقية تحذير `DEGRADED` لمُنقّي الأسرار إلى خروج حاجب. افتراضيًا، يطبع فشل الإخفاء `secret redaction DEGRADED` إلى stderr ويترك المخرَج يمرّ؛ الوضع الصارم يرفض إصدار أي شيء لم يستطع المنقّي تنظيفه كاملًا. استخدمه في CI أو على الأجهزة المشتركة حيث سطر غير مُخفَى أسوأ من أمر فاشل. | -| `FORGE_NO_UPDATE_CHECK=1` | إسكات إشعار "commits behind upstream" في `forge doctor`. | -| `FORGE_NO_HINT=1` | كتم تلميح init المُعروض لمرة واحدة الذي يدفعك إلى تشغيل `forge init`. | -| `FORGE_VERBOSE=1` | إظهار عنوان الأمر (`Forge — …`) المخفي افتراضيًا. | -| `FORGE_EMBED=1` | تفعيل طبقة التضمينات لاسترجاع الذاكرة (يبقى MinHash افتراضًا بدون تبعيات). | -| `FORGE_LEDGER_ONLY=0` | منفذ هروب. وضع «السجل فقط» هو الافتراضي — تعيش الذاكرة في `.forge/ledger` فقط، ولم تعد ملفات `lessons/*.md` وملفات الحقائق القديمة تُكتب. اضبطه على `0` لاستعادة مخزن الملفات القديم. | - - - شغّل `forge --help` للقائمة المحدَّثة دائمًا، أو `forge catalog` لفهرس البدء لكل - أداة وطاقم وحاجز مع سبب موجز. - - -## أوامر وعلامات أحدث - -هذه الأوامر والعلامات متاحة. موثقة في صفحات مجموعاتها وموسومة داخل النص: - -| الأمر / العلامة | المجموعة | ماذا يفعل | -| ---------------------- | -------- | ----------------------------------------------- | -| `forge know` | Memory | توجيه حقيقة إلى موطن تخزينها الصحيح. | -| `forge deja` | Memory | بحث عن أعمال سابقة مماثلة. | -| `forge precommit` | Quality | بوّابة تحقق على مستوى الالتزام. | -| `forge radar` | Quality | حلقات حداثة التبعيات. | -| `forge report` | Config | تقرير HTML ثابت عن حالة Forge للمستودع. | -| `forge tools` | Config | اختيار الأداة الأساسية + توصيل gitignore. | -| `forge verify --deep` | Quality | تحقق بإجماع متعدد العدسات. | -| `forge update --to` | Core | التثبيت أو الرجوع إلى إصدار معيّن. | diff --git a/mintlify/ar/cli/quality.mdx b/mintlify/ar/cli/quality.mdx deleted file mode 100644 index fb16c87..0000000 --- a/mintlify/ar/cli/quality.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "أوامر Quality" -description: "التحقق والسلامة: verify وscan وspec وtaste وuicheck وharden — إضافةً إلى بوّابتَي precommit وradar." ---- - -مجموعة Quality هي سطح التحقق والسلامة. راجع -[بوّابات التحقق](/ar/concepts/verification-gates) لكيفية تركيبها. - -## `forge verify` - -بوّابة تحقق مستقلة — اختبارات + رمز مُهلوَس + مصدرية. - -```bash -forge verify -forge verify --deep # multi-lens consensus -``` - -يُبلِّغ `forge verify --deep` عن `status` رباعي الحالات بدلًا من نجاح/إخفاق ثنائي: - -| الحالة | المعنى | -| ---------------- | ------------------------------------------------------------------------------------- | -| `PASS` | اتفقت جميع العدسات **و** حالة اختبارات `forge verify` الأساسية هي أيضًا `PASS`. | -| `FAIL` | أبلغت عدسة واحدة على الأقل عن إخفاق حقيقي. | -| `INCOMPLETE` | لم تتمكن عدسة من الإنهاء (مهلة، أو تعطل، أو تبعية مفقودة) — تُعامَل كأنها غير مُثبَتة. | -| `NOT_CONFIGURED` | لا توجد عدسات موصولة بهذا المستودع — لم يُفحَص شيء فعليًا. | - -`PASS` وحدها تُعتبر تحققًا. يرفض `--deep` عمدًا ترقية الإجماع إلى `PASS` عندما تكون حالة -اختبارات `forge verify` الأساسية أي شيء غير `PASS`، بحيث يستلزم اجتياز الفحص العميق -اجتياز الفحص الأساسي دائمًا. - -## `forge scan` - -بوّابة المهارات — فحص مهارة أو خادم MCP بحثًا عن الحقن / RCE / التسريب قبل التثبيت. - -```bash -forge scan -``` - -## `forge spec` - -المواصفة كعقد — init (OpenSpec)، وقفل، وفحص الانحراف. - -```bash -forge spec init -forge spec lock -forge spec check -``` - -## `forge taste` - -تمكين أداة ذوق واحدة لواجهة المستخدم لهذا المستودع (بدون وسيط يعرض الخيارات). - -```bash -forge taste # list the profiles -forge taste # brutalist · corporate · editorial · minimalist · playful -``` - -يكتب `DESIGN.md` ويُعدّل عتبات بوّابة `uicheck design`. - -## `forge uicheck` - -فحوصات حتمية لواجهة المستخدم. - -```bash -forge uicheck contrast # WCAG contrast ratio -forge uicheck fingerprint # deterministic design fingerprint -forge uicheck design # slop-distance + conformance gate -forge uicheck visual # Playwright-rendered check (opt-in tier) -``` - -## `forge harden` - -توصيل ضوابط الأمان — gitleaks قبل الالتزام + إعدادات الصندوق الرملي. - -```bash -forge harden -``` - -## `forge precommit` - -بوّابة على مستوى الالتزام — تُشغّل الحد الأدنى للتحقق عند وقت الالتزام، فيُلتقط -العمل الجزئي أو غير المُتحقَّق منه قبل أن يستقر. - -```bash -forge precommit -``` - -## `forge radar` - -حلقات حداثة التبعيات — تُجمِّع تبعيات المشروع بحسب مدى حداثتها، ليظهر ما هو بائت أو -منحرف قبل أن يعضّ. - -```bash -forge radar -``` - -راجع دليل [إبقاء التبعيات محدَّثة](/ar/guides/radar-deps) لكيفية قراءة الحلقات. diff --git a/mintlify/ar/cli/substrate.mdx b/mintlify/ar/cli/substrate.mdx deleted file mode 100644 index 4e72566..0000000 --- a/mintlify/ar/cli/substrate.mdx +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: "أوامر Substrate" -description: "بوّابة ما قبل الفعل ومراحلها القابلة للاستدعاء فرديًا: substrate وpreflight وroute وimpact وscope وcontext وanchor وdiagnose وimagine وlean." ---- - -مجموعة Substrate هي بوّابة ما قبل الفعل. يُركّب `forge substrate` بقية المراحل في حكم -واحد؛ وكل مرحلة قابلة للاستدعاء بمفردها. راجع -[بوّابة ما قبل الفعل](/ar/concepts/pre-action-gate) للحصول على الأنبوب. - -## `forge substrate` - -بوّابة ما قبل الفعل الواحدة: الافتراضات، والتوجيه، والأثر، والنطاق، والذاكرة، والتحقق. - -```bash -forge substrate "" -forge substrate "" --json -``` - -إذا أرجع `okToProceed:false`، اسأل `assumption.questions` المُرجَعة قبل التعديل. - -## `forge preflight` - -فحص الافتراضات — ما تُسمّيه المهمة ولا يُعرِّفه المستودع. - -```bash -forge preflight "" -``` - -## `forge route` - -اقتراح أرخص نموذج قادر على المهمة. - -```bash -forge route "" -forge route gateway # emit LiteLLM gateway config -``` - -## `forge impact` - -توقّع نصف قطر الانفجار لرمز أو ملف من رسم الأطلس. - -```bash -forge impact -``` - -## `forge scope` - -تفكيك الملفات إلى عناقيد مستقلة — إضافةً إلى الملفات المترابطة التي لم تسمِّها. - -```bash -forge scope -``` - -## `forge context` - -تجميع سياق موزون بميزانية + بوّابة اكتمال — ما يحتاج التعديل أن يُعرف. - -```bash -forge context "" -``` - -يُجمّع سياقًا موزونًا بميزانية عبر تغطية مجموعة (set-cover) فوق مجموعة التعديل المتوقعة، -ويُطبّق سلم ضغط، ويُبلغ عن مجموعة المفقودات المحسوبة. - -## `forge anchor` - -فحص انحراف الهدف — هل ما زالت تغييراتك الفعلية (في git) على الهدف المُعلن؟ - -```bash -forge anchor set "" # persist the goal across sessions -forge anchor show -forge anchor clear -``` - -## `forge diagnose` - -فحص الحلقة الهالكة — سجِّل إخفاقًا؛ فالتوقيع نفسه 3× يولّد تشخيصًا + تصعيدًا. - -```bash -forge diagnose "" -``` - -## `forge imagine` - -محاكاة العواقب — أعطال متوقعة + الحد الأدنى من مجموعة الاختبارات (dry-run) لمهمة. - -```bash -forge imagine "" -forge imagine "" --run # execute the minimal suite sandboxed -``` - -## `forge lean` - -الحد الأدنى للنطاق (M5) — قياس بصمة الفرق مقابل ما طلبته المهمة. - -```bash -forge lean -``` - - - تعمل مراحل `route` و`impact` و`scope` و`context` و`anchor` و`lean` كلها داخل - `forge substrate`. استدعِها فرديًا حين ترغب في إشارة واحدة فقط. - diff --git a/mintlify/ar/concepts/config-compiler.mdx b/mintlify/ar/concepts/config-compiler.mdx deleted file mode 100644 index 76a0e26..0000000 --- a/mintlify/ar/concepts/config-compiler.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "مُصرِّف الإعدادات رباعي الطبقات" -description: "اكتب الركيزة مرة واحدة؛ يُصرِّفها forge sync إلى الإعداد الأصلي لكل أداة. الطبقات الأربع هي كيف يُعبَّر عن الدماغ؛ والمُصرِّف هو كيف يُوصَل." ---- - -تكتب الركيزة مرة واحدة. يُصرِّف `forge sync` هذا المصدر إلى الإعداد الأصلي لكل أداة. -الطبقات الأربع هي _كيف يُعبَّر عن الدماغ_؛ والمُصرِّف هو _كيف يُوصَل_. - -```mermaid -flowchart TD - S["source/ · rules.json · substrate.json · mcp.json"] -->|"forge sync — content-hash + DO-NOT-EDIT headers"| N["native configs · CLAUDE.md · AGENTS.md · .cursor · .gemini · .aider"] - S -. configures .-> L - subgraph L["the four layers"] - direction LR - T["tools · model-invoked skills"] - C["crew · isolated sub-agents"] - G["guards · deterministic hooks"] - M["mcp · atlas + substrate server"] - end -``` - -## مصدر واحد، مُصدِرات عديدة - -اكتب القواعد **مرة واحدة** (`source/rules.json`)؛ يُصدر مُصرِّف حتمي (`forge sync`) -الصيغة الأصلية لكل أداة بترويسة تجزئة للمحتوى، فيصبح الانحراف قابلًا للكشف وإعادة -التشغيل بلا أثر. لا تُكتب قاعدة مرتين أبدًا. المصدر القانوني ثلاثة ملفات: - -| ملف المصدر | ما يحويه | -| ----------------------- | -------------------------------------------------------------------- | -| `source/rules.json` | القواعد الهندسية القانونية (git، الاختبارات، الأمن، الأسلوب). | -| `source/substrate.json` | الإعدادات الافتراضية للركيزة المعرفية — العتبات، والتوجيه، ومقابض LLM. | -| `source/mcp.json` | تعريفات خوادم MCP التي تُصدر لكل أداة. | - -## الطبقات الأربع - -كل طبقة لها اسم علامة تجارية وتُصدر عبر الأدوات. - - - - `~/.forge/tools/` → `~/.claude/skills/`. مهارات يستدعيها النموذج، تتبع معيار - `SKILL.md` (بيانات وصفية `name` + `description`). - - - `~/.forge/crew/` → `~/.claude/agents/`. وكلاء فرعيون معزولون السياق، مثل - الاستكشاف، والتحقق، والتحقق الأمامي. - - - `~/.forge/guards/` → خطّافات `settings.json`. **الطبقة الوحيدة التي _تُنفِّذ_ بدلًا - من الاقتراح.** الحاجز خطّاف حتمي لا يستطيع النموذج الانحراف عنه. تُعترف القواعد - النصية في `CLAUDE.md` ثم تُنسى بعد الضغط؛ الحاجز لا يُنسى. كل ثابت قابل للتنفيذ - ينتمي هنا. - - - يشحن Forge خادم stdio واحدًا (`src/cortex_mcp.js`) يعرض 19 أداة MCP: فحوصات - الركيزة (`substrate_check` / `predict_impact` / `assumption_gate` / …)، - قراءات _وكتابات_ الذاكرة (`forge_remember`، ledger ratify/retract)، والصحة. - - - -تخترق الشواغل العابرة الطبقات الأربع كلها: **atlas** (رسم الشيفرة)، و**lean** -(الحد الأدنى — يُشحن كأداة وكحاجز إيقاف، فيسري سواء استدعاه النموذج أم لا)، و**recall** -(الذاكرة). - -## الحاجز فوق النص - -القواعد التي يمكن للنموذج الانحراف عنها تعيش في النص؛ والقواعد التي **لا يجوز له** -كسرها تعيش في الحواجز (خطّافات shell حتمية). لا يمكن نسيان الحاجز بعد ضغط السياق. - - - انقل كل ثابت قابل للتنفيذ من `CLAUDE.md` إلى حاجز؛ واحتفظ بالنص رقيقًا. هذا هو - أهم انضباط منفرد في تصميم Forge. - - -## مصفوفة الإصدار المتحقق منها عبر الأدوات - -يُصدر Forge إعدادات لـ **تسع أدوات**، إضافةً إلى خادم MCP لأدوات Roo Code وVS Code. -كل صف مُوثَّق بالرجوع إلى وثائق المورّد. - -| الأداة | الهدف الأصلي | كيف يُصدر Forge | -| ------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------- | -| **Claude Code** | `CLAUDE.md` (+ `.claude/rules/*.md`، `settings.json`) | `CLAUDE.md` رقيق يبدأ سطره الأول بـ `@AGENTS.md`؛ الحواجز → settings | -| **Codex** | `AGENTS.md` أصلي (سقف 32 KiB) | `AGENTS.md` القانوني في الجذر **هو** المصدر | -| **Cursor** | `AGENTS.md` + `.cursor/rules/*.mdc` | `AGENTS.md` للقواعد المسطحة؛ `.mdc` عند الحاجة إلى نطاق | -| **Gemini** | `GEMINI.md`، أو `AGENTS.md` عبر تفعيل `context.fileName` | يكتب `.gemini/settings.json` لتفادي نسخة ثانية | -| **Aider** | `CONVENTIONS.md` عبر `read:` في `.aider.conf.yml` | يُصدر `.aider.conf.yml` مع `read: AGENTS.md` | -| **Copilot** | `AGENTS.md` في الجذر + `.github/copilot-instructions.md` | يعتمد على `AGENTS.md` في الجذر؛ مؤشر `.github` اختياري | -| **Windsurf/Devin** | `AGENTS.md` مكتشَف تلقائيًا (سقف 6k/12k حرفًا) | `AGENTS.md` جذري تحت الحد؛ يميز بين `.windsurf` و`.devin` | -| **Zed** | أول مطابقة من قائمة أولوية تشمل `AGENTS.md` | يُصدر `AGENTS.md`؛ يُشير الطبيب لأي ملف قديم مُظلِّل | -| **Continue** | `.continue/rules/*.md` + `.continue/mcpServers/*.yaml` | يُصدر ملف قواعد + إعداد خادم Forge MCP | - -تتلقّى Roo Code وVS Code خادم Forge MCP عبر `forge init` (`.roo/mcp.json`، -`.vscode/mcp.json`) بدلًا من ملف قواعد. - - - **حدود عدد المحارف حقيقية.** يبتر Codex عند 32 KiB، وWindsurf عند 6k/12k. يفرض - `forge sync` ميزانية حجم للمصدر بحيث لا يُبتر إعداد بصمت. - diff --git a/mintlify/ar/concepts/cross-session-memory.mdx b/mintlify/ar/concepts/cross-session-memory.mdx deleted file mode 100644 index 9907217..0000000 --- a/mintlify/ar/concepts/cross-session-memory.mdx +++ /dev/null @@ -1,91 +0,0 @@ ---- -title: "الذاكرة عبر الجلسات" -description: "تثبيت الجلسة، وبوّابة الإكمال، ولقطات التسليم، وسجل القرارات — الطبقة التي تقتل فقدان ذاكرة الجلسة والعمل الجزئي." ---- - -نمطان من الإخفاق تُوجد هذه الطبقة لتقتلهما: **العمل الجزئي** (تغييرات في الشيفرة دون -القطع التي تعتمد عليها) و**فقدان ذاكرة الجلسة** (الجلسة التالية تعيد افتراض ما عرفته -هذه الجلسة). التعليمات ترفع _احتمال_ السلوك الصحيح؛ والخطّافات الحتمية تضمن _حدًّا -أدنى_. - -## تثبيت الجلسة - -عند `SessionStart` (`src/session.js`)، يسجل Forge `HEAD` مرة واحدة لكل جلسة، ويُقلّم -قطع الجلسات الأقدم من أسبوع، ويحقن توجيهًا طازجًا: - - - - دروس Cortex المستنبطة من التصحيحات الماضية. - - - الهدف المُعلن، بحيث يمكن قياس الانحراف مقابله. - - - ملف `.forge/state.md` المحدود الذي كتبته الجلسة السابقة. - - - أحدث الالتزامات والتغييرات غير المُلتزَم بها — أدلة لا افتراضات. - - - -تتوجّه الجلسة الجديدة بالأدلة، لا بالافتراضات المسبقة. - -## بوّابة الإكمال - -الحاجز الوحيد الذي قد يُجيب على مسار Stop هو `completion-gate.sh` -(`src/gate.js`). يعمل بشكل متزامن؛ يظل `cortex.sh stop` الخاص بتنقيب الدروس -منفصلًا ولا يستطيع الحجب أبدًا. - -مجموعة التغييرات محدودة بالجلسة: الملفات من الالتزامات التي زمن مُلتزمها عند بداية -الجلسة أو بعدها، إضافةً إلى تغييرات شجرة العمل ناقصًا الأوساخ المُلتقطة عند -`SessionStart` — بحيث لا تُلصَق التعديلات السابقة، وتبديل الفروع، و`git pull` بالوكيل. - - - إذا تحرّكت الشيفرة دون أن يتبعها توثيق أو أثر حالة، تحجب البوّابة **مرة واحدة** مع - قائمة إصلاح كسبب. كل حالة أخرى تسمح، وكل خطأ داخلي يسمح (فشل بلطف). - `FORGE_STOPGATE=0` يوقفه. - - -بالنسبة للجلسات التي غيّرت الشيفرة، تشترط البوّابة أيضًا **دليلًا اختباريًا** — إما ملف -اختبار في فرق الجلسة، أو تشغيلًا طازجًا ناجحًا لـ `forge verify` مقابل التغييرات -الحالية. لم تعُد لقطة `forge handoff` وحدها كافية لتجاوز فرع تغيير الشيفرة من البوّابة. - -قائمة الإصلاح تُشير إلى الأدوات التي تُنهي العمل: - -```bash -forge verify # record the test evidence for code changes -forge docs sync # sweep the diff for stale doc mentions -forge handoff "" --next "" # write the bounded session snapshot -forge decide " — " # record a choice so no session re-decides it -``` - -## التسليم والقرارات - -مخزنان يحفظان المعرفة عبر الجلسات: - -| المخزن | الدلالة | -| -------------------- | ------------------------------------------------------------------------------------ | -| `.forge/state.md` | **إعادة كتابة** محدودة (لقطة) — تكلفة التحميل تبقى `O(bound)` إلى الأبد. | -| `.forge/decisions.md`| **ADR-lite** إضافي فقط (`D-####`) مع توأم آلي القراءة لسجل القرارات. | - -كلاهما يرفض الأسرار عند الكتابة. يُعاد حقن `state.md` عند بداية كل جلسة؛ ويُقرأ -`decisions.md` قبل إعادة تقرير أي شيء استقرّت عليه جلسة سابقة. - -```bash -forge handoff "" --next "" -forge decide " — " -forge decide # read the log before re-deciding -``` - -## مسح التوثيق المدفوع بالفرق - -يُجيب `forge docs sync` عن السؤال ذي الشكل الفرقي: المعرِّفات المُغيَّرة (المسارات، -والتعاريف، والرموز المُستدعاة، من الأسطر المضافة _والمحذوفة_) مقابل كل قطعة توثيق -→ UPDATED / STALE (مع إصابات file:line) / VERIFIED-UNAFFECTED، مع تسجيل السبب. هو -مُبلِّغ محض؛ بوّابة الإكمال توفر الأسنان. - - - `recall` و`cortex` ذاكرة ملفات وطلبات فقط — **ليست** تعلمًا على مستوى الأوزان. - التجميع مُلخِّص قد يُهلوس، لذا يبقى إرشاديًا وقابلًا لمراجعة الإنسان وخاليًا من - الأسرار. - diff --git a/mintlify/ar/concepts/model-routing.mdx b/mintlify/ar/concepts/model-routing.mdx deleted file mode 100644 index aca2fbe..0000000 --- a/mintlify/ar/concepts/model-routing.mdx +++ /dev/null @@ -1,78 +0,0 @@ ---- -title: "توجيه النماذج" -description: "معيار حتمي وقابل للمقارنة (diffable) يختار أرخص فئة نموذج قادرة قبل الإرسال — مع إعادة تعيين آمنة للفشل لبوابات المستضافة ذاتيًا." ---- - -يوصي Forge بأرخص نموذج قادر على تنفيذ مهمة ما **قبل** الإرسال، وذلك من خلال معيار حتمي -يمكنك قراءته في المستودع (`src/model_tiers.json`). على عكس البوابة التي تتخذ القرار -داخل الوكيل (proxy) وقت الطلب، فإن قرار التوجيه هنا مرئي وقابل للمقارنة في git. - -## التوصية بفئة — `forge route` - -```bash -forge route "" # cheapest capable model tier for the task -forge route gateway # emit LiteLLM gateway config -``` - -التوصية عبارة عن حسابات k-NN مبنية على أمثلة نموذجية فوق بنك موسوم (صفوف بالإنجليزية -+ Hinglish) وفق مقياس تشابه بالتداخل مع بوابة ثقة — وليست مجرد بحث بالكلمات المفتاحية. - - - ابدأ من `route.tier` الموصى به ولا تصعّد إلا بعد فشل مُحقِّق خارجي، لا بشكل استباقي أبدًا. - هذا يبقي الإنفاق منخفضًا دون تقييد القدرة عندما تحتاج المهمة إليها فعلًا. - - -## النية أولًا، ثم الفئة - -يشترك التوجيه في الحسابات مع اكتشاف النية (`src/intent.js`): يُطابَق الموجّه (prompt) مع -نية معينة عبر مقدِّر k-NN القائم على الأمثلة النموذجية ذاته. لاحظ أن الاثنين يستخدمان -مجموعات إيقاف مختلفة — التوجيه يعامل الأفعال العامة (`fix` / `add` / `build`) -كضوضاء تعقيد، بينما هذه الأفعال بالضبط هي إشارة النية. - -## جدول الفئات - -يُثبِّت جدول الفئات (`src/model_tiers.json`) معرفات نماذج Anthropic العامة حسب العائلة -(haiku / sonnet / opus / fable). تُوفَّق أسعار المستندات مع هذا الملف عبر فحص المستندات، -بحيث لا يمكن أن ينحرف النص عن الجدول. - -## إعادة التعيين للبوابات المستضافة ذاتيًا - -بوابة LiteLLM أو وكيل مستضاف ذاتيًا يقدّم أسماء نماذجه الخاصة، لذا فإن إرسال معرف قياسي -حرفيًا سيؤدي إلى خطأ 404. عند تكوين عنوان URL أساسي لبوابة غير افتراضية، يقوم Forge -(`src/gateway_model_map.js`) بجلب `GET /v1/models` **مرة واحدة لكل عملية** ويسجّل نقاطًا -لكل معرف مُعلَن مقابل عائلة كل فئة: - - - - يجب أن تتطابق كلمة العائلة (haiku / sonnet / opus / fable) — وهي بوابة صارمة. - - - ضمن العائلة، يختار معامل `setOverlap` لرموز اسم الفئة أفضل تطابق. - - - يُحسم التعادل لصالح المعرف الأقرب إلى الاسم القانوني. - - - - - تستشير إعادة التعيين البوابة **فقط** عندما يكون المعرف المُحلَّل معرفًا _قياسيًا_ — لا يتم - المساس أبدًا باسم مستعار صريح في `.forge/providers.json` أو تجاوز `ANTHROPIC_MODEL`. - يفشل بأمان إلى المعرف القياسي عند غياب البوابة، أو تعذر الوصول إلى `/v1/models`، - أو عدم وجود تطابق عائلي، وبذلك يكون المستخدمون المباشرون لـ `api.anthropic.com` - متطابقين بايتًا ببايت. - - -يطبع صف **gateway models** في `forge doctor` تعيين `tier → model` المُحَل للتحقق. - -## المزودون والتكلفة - -```bash -forge config # show / switch / add providers, set the default model -forge cost # real per-day spend -forge cost --stages # measured per-stage cost factors -``` - - - يُبلِّغ `forge cost --stages` عن **المراحل المُقاسة فقط** — المرحلة التي لا تحتوي على - أحداث تقول "no data"، ولا تعرض قيمة افتراضية أبدًا. أي رقم يظل افتراضًا حتى يُقاس. - diff --git a/mintlify/ar/concepts/pre-action-gate.mdx b/mintlify/ar/concepts/pre-action-gate.mdx deleted file mode 100644 index 69b9056..0000000 --- a/mintlify/ar/concepts/pre-action-gate.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: "بوابة ما قبل الإجراء" -description: "يُشغّل forge substrate تمريرة مرتبة واحدة من الفحوصات قبل أن يعدّل النموذج الشيفرة ويعيد حكمًا واحدًا — الافتراضات، والتوجيه، والتأثير، والنطاق، والذاكرة، والتحقق." ---- - -**الركيزة الإدراكية (Cognitive substrate)** — الطبقة التي تعمل _قبل_ أن يعدّل النموذج الشيفرة. -يُشغّل `forge substrate ""` (وأداة MCP المسماة `substrate_check`) تمريرة مرتبة واحدة -من الفحوصات ويعيد حكمًا واحدًا. تُركّب هذه البوابة المراحل القابلة للاستدعاء بشكل مستقل — -`preflight`، `route`، `atlas`، `impact`، `reuse`، `context`، `scope`، `lean`، `anchor`، -`verify` — في عقد واحد لما قبل الإجراء. - -```mermaid -flowchart TD - RE["referenced entities"] --> INTAKE - subgraph INTAKE["intake"] - direction LR - PF["preflight · assumption gap"] --> RT["route · cheapest tier"] - end - INTAKE --> ANALYSIS - subgraph ANALYSIS["analysis"] - direction LR - AT["atlas · code graph"] --> IM["impact · blast radius"] --> PT["predict · failing tests"] --> RU["reuse · cache hit?"] - end - ANALYSIS --> SAFETY - subgraph SAFETY["safety + fit"] - direction LR - CX["context · completeness gate"] --> SC["scope · coupled files"] --> ME["memory · recall + lessons"] --> MN["minimality · lean footprint"] --> GA["goal-anchor · drift check"] - end - SAFETY --> VD["verdict"] -``` - -## المراحل الثلاث - - - - يجد **preflight** فجوة الافتراضات — ما تسميه المهمة ولم يُعرَّف في المستودع. - يختار **route** أرخص فئة نموذج قادرة. - - - يقرأ **atlas** الرسم البياني للشيفرة، ويحسب **impact** نصف قطر الانفجار، - ويسمّي **predict** الاختبارات المرجّح فشلها، ويتحقق **reuse** من وجود ضربة تخزين مؤقت - مُتحقَّق منها. - - - يُشغّل **context** بوابة الاكتمال، ويُظهر **scope** الملفات المقترنة، وتُحقن - **memory** الاستدعاء + الدروس، ويقيس **minimality** البصمة الرشيقة، - ويفحص **goal-anchor** الانحراف. - - - -## نصف قطر الانفجار - -**نصف قطر الانفجار (Blast radius)** — مجموعة الملفات التي يُتوقع أن يؤثر عليها التعديل، -مقروءةً من الرسم البياني للشيفرة. يحسبه `forge impact`؛ ويكشفه خط الأنابيب قبل أن يمس -النموذج أي شيء. - -```bash -forge impact verifyToken # predicted impacted files for a symbol -forge impact src/auth.js # …or for a file -``` - -## استشاري بشكل افتراضي - -الحكم **استشاري بشكل افتراضي** — يُبلِّغ ولا يحجب. عيّن `FORGE_ENFORCE=1` لتحويل -أقوى الإشارات إلى حجب صارم: - - - - لم يجد preflight نية قابلة للتنفيذ — مهمة غير محددة بشكل كافٍ. - - - لا تستطيع بوابة الاكتمال تغطية مجموعة التعديلات المتوقعة. - - - تتجاوز مجموعة الملفات المتأثرة عتبة الافتراضية ~25 ملفًا. - - - -كل شيء آخر يظل تحذيرًا يمكن للإنسان تجاوزه. - - - على Claude Code تعمل البوابة بأكملها **على كل موجّه تلقائيًا** عبر خطاف `UserPromptSubmit` — - صامتة في المهام النظيفة. يقدم `forge substrate "" --json` الحكم القابل للقراءة آليًا - لأغراض البرمجة النصية. - - -## كيف تشغّلها - -```bash -forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" -forge substrate "" --json -``` - -إذا كان الحكم `ASK FIRST`، فاسأل الأسئلة الواردة في `assumption.questions` قبل التعديل — -لا تخمّن مهمة غير محددة بشكل كافٍ. ابدأ من `route.tier` الموصى به ولا تصعّد إلا بعد فشل -مُحقِّق خارجي، لا استباقيًا أبدًا. - - - تقرأ مرحلة الذاكرة من السجل الحامل للإثبات. - diff --git a/mintlify/ar/concepts/proof-carrying-memory.mdx b/mintlify/ar/concepts/proof-carrying-memory.mdx deleted file mode 100644 index 33d47b8..0000000 --- a/mintlify/ar/concepts/proof-carrying-memory.mdx +++ /dev/null @@ -1,109 +0,0 @@ ---- -title: "الذاكرة الحاملة للإثبات" -description: "كل حقيقة أو درس أو أثر إعادة استخدام مُخزَّن هو ادعاء يحمل دليله الخاص — ولا يُوثَق به إلا بعد أن ترفع أدوات تحقق مستقلة ثقته فوق حد أدنى." ---- - -**الذاكرة الحاملة للإثبات (Proof-carrying memory أو PCM)** — كل حقيقة أو درس أو أثر إعادة استخدام -مُخزَّن هو _ادعاء_ يحمل دليله الخاص. ولا يُوثَق به إلا بعد أن ترفع أدوات تحقق مستقلة -(اختبارات، CI، قبول/تراجع بشري) ثقتَه فوق حد أدنى. الدرس الخاطئ يضمحل بدلًا من أن يتحجّر. - - - "الذاكرة الحاملة للإثبات" هو اسمنا لـ **ذاكرة مرجعية بالأدلة ومُعنونة بالمحتوى** — ادعاء يُعنون - بتجزئة (hash) محتواه ويُربط بنتائج أدوات التحقق التي تدعمه. "الإثبات" هو مسار الأدلة هذا - مضافًا إليه قاعدة الثقة، **وليس إثباتًا رسميًا مُتحقَّقًا آليًا**؛ لا يوجد مثبت نظريات في الحلقة. - - -## مخزن واحد، كتّاب متعددون - -تلتقي كل أنظمة الذاكرة الفرعية في مخزن واحد. تكتب `recall`، و`remember`/`brain`، -ودروس `cortex`، وآثار `reuse`، ونتائج `diagnose` للحلقة المكسورة جميعها ادعاءات مُعنونة -بالمحتوى في `.forge/ledger/`. - -```mermaid -flowchart LR - subgraph EV["local events"] - direction TB - E1["recall / remember"] - E2["cortex lesson"] - E3["reuse mint"] - E4["diagnose"] - end - EV -->|"content-addressed claims"| LG["(.forge/ledger)"] - O["independent oracles · tests · CI · human accept/revert"] -->|"append evidence · move confidence"| LG - TM["teammate ledgers"] <-->|"git union-merge · conflict-free"| LG - LG --> RV["merged read view · recall list · lesson inject · brain index"] -``` - -## لماذا يتلاقى دون تعارضات - -لأن بايتات الادعاء هي دالة صرفة من `(kind, body, scope)`، فإن كل نسخة تحسب نفس الهوية — -لذا تُطوى سجلات زملاء الفريق معًا فوق git العادي دون أي تعارض. - -ميكانيكيًا: - -- **الأدلة وشواهد القبور (tombstones) قابلة للإلحاق فقط**، وهي سجلات مُزالة التكرار عبر التجزئة. -- **الثقة (`val`)** هي احتمال بايزي لاحق (Beta posterior) مُتحلِّل، ولا تحرّكه سوى أدوات التحقق. -- **الدمج هو شبكة نصف اتصال (join-semilattice)** — مُختبَرة بخصائص تُثبت أنها تبادلية، - وتجميعية، وعديمة القوة (idempotent) — فتتلاقى السجلات بأي ترتيب. - - - يُصدر `forge init` قاعدة `.gitattributes` الخاصة بدمج الاتحاد (union-merge) التي يحتاجها السجل؛ - ويطوي `forge ledger merge ` أي شجرة سجل أخرى. القرار الكامل موثق في ADR-0006 - (proof-carrying memory). - - -## أدوات التحقق تحرّك الثقة — ولا شيء آخر - -فقط أدوات التحقق المستقلة يمكنها تحريك ثقة الذاكرة: - - - - اختبار ناجح يمارس الادعاء يرفع ثقته. - - - خط أنابيب أخضر هو دليل مستقل على أن الادعاء لا يزال قائمًا. - - - قبول صريح أو تراجع هو الإشارة الأقوى من الجميع. - - - -الأدلة غير القابلة للتحقق يرفضها جدول `ORACLES` مغلق (`src/ledger.js`). المعرفة غير المُراجَعة -تضمحل نحو _عدم اليقين_، وليس الحذف — تُحفظ الادعاءات الخاملة للتدقيق، ولا تُزال بصمت أبدًا. - -## واجهة السجل - -```bash -forge ledger stats # what the repo knows, by kind and trust level -forge ledger verify # re-check claims are in normal form -forge ledger show # a claim and its evidence trail -forge ledger blame # who minted it, every oracle outcome, per-author trust -forge ledger query "" # retrieve claims by relevance -forge ledger ratify # human accept -forge ledger retract # tombstone a claim -forge ledger merge # fold a teammate's ledger in, conflict-free -forge ledger import # bridge legacy stores into the ledger -``` - -أضف `--personal` للسجل الخاص بكل مستخدم. - -## ذاكرة إعادة الاستخدام تحمل الإثبات أيضًا - -`forge reuse` هو ذاكرة تخزين مؤقت للشيفرة تحمل الإثبات. لا يُقدَّم أثر مُولَّد مرة أخرى إلا -عندما يظل دليله قائمًا — أي أن الثقة فوق الحد الأدنى **و** لا تزال تبعيات atlas الخاصة به -قابلة للحل. وإلا فإنه يسقط إلى مرحلة التوليد ويسك ادعاءً جديدًا في طريق العودة. - -```mermaid -flowchart LR - SP["spec"] --> FP["fingerprint · MinHash + LSH"] - FP --> LD["match ladder · exact to near to adapt to miss"] - LD --> GT{"confidence >= floor AND deps resolve?"} - GT -->|"yes"| SV["serve · proof holds"] - GT -->|"miss"| GN["generate"] - GN -->|"mint claim"| MT["(.forge/ledger)"] -``` - - - تطابق MinHash القريب ضعيف على المواصفات القصيرة جدًا. توفر واجهة تضمينات اختيارية - (`FORGE_EMBED`) حلًا لذلك؛ ويبقى MinHash الافتراضي الخالي من التبعيات. - diff --git a/mintlify/ar/concepts/verification-gates.mdx b/mintlify/ar/concepts/verification-gates.mdx deleted file mode 100644 index 1f05bd8..0000000 --- a/mintlify/ar/concepts/verification-gates.mdx +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: "بوابات التحقق" -description: "التحقق المستقل، وعَلَم الرمز المُهلوَس، والمواصفة-كعقد، وبوابة المهارات — فحوصات يمكنك تشغيلها تُقلِّل الأخطاء لكنها لا تُشهد بالصحة أبدًا." ---- - -لا شيء يُعد "منجَزًا" دون فحص يمكنك تشغيله — اختبار، أو رمز خروج من البناء، أو لقطة شاشة. -تضيف كل من بوابات التحقق في Forge حاجزًا إضافيًا للاصطياد. مع معدل إخفاق لكل مهمة قدره -`1 − p` ومعدل اصطياد للبوابة `c`، تنخفض الإخفاقات الصامتة إلى `(1 − p)(1 − c)`، وكل بوابة -هنا هي `c` إضافية. - - - **التحقق يُقلِّل الأخطاء، ولا يُشهد بها.** مُحقِّقو الفريق (Crew) وعَلَم الرمز المُهلوَس يقلّلان - عبء المراجعة؛ لكنهما لا يثبتان صحة الشيفرة. الاختبارات والتصحيحات البشرية تفوز دائمًا. - - -## التحقق المستقل — `forge verify` - -بوابة مستقلة: تُشغّل اختبارات المستودع الحقيقية، وتضع علامة على الرموز المُهلوَسة، -وتتحقق من المصدر (provenance). - -```bash -forge verify # tests + hallucinated-symbol + provenance -forge verify --deep # multi-lens consensus — several independent checks must agree -``` - - - يُصعّد `--deep` إلى إجماع متعدد العدسات: يجب أن يجتاز التغيير عدة عدسات - تحقق مستقلة، لا عدسة واحدة فقط. - - -يُبلِّغ `forge verify --deep` عن `status` رباعي الحالات، لا نجاح/إخفاق ثنائيًا: - -- `PASS` — اتفقت جميع العدسات **و** حالة اختبارات `forge verify` الأساسية هي أيضًا - `PASS`. هذه الحالة وحدها تُعدّ تحققًا. -- `FAIL` — أبلغت عدسة واحدة على الأقل عن إخفاق حقيقي. -- `INCOMPLETE` — لم تتمكن عدسة من الإنهاء (مهلة، أو تعطل، أو تبعية مفقودة). لم يُدحَض - شيء، لكن لم يُثبَت شيء كذلك. -- `NOT_CONFIGURED` — لا توجد عدسات موصولة بهذا المستودع، فلم يجد `--deep` ما يفحصه. - -قاعدة أن `PASS` تستلزم `PASS` في الفحص الأساسي مقصودة: لا يمكن لإجماع عميق أخضر أن -يتجاوز تشغيلًا أساسيًا أحمر، لذا فإن `INCOMPLETE` أو `NOT_CONFIGURED` على عدسة الاختبار -الأساسية يُخفّض نتيجة الفحص العميق لتطابقها. - -## عَلَم الرمز المُهلوَس — `forge atlas has` - -`forge atlas has ` هو فحص الهلوسة: إذا استدعى النموذج رمزًا ليس في الرسم البياني -للشيفرة، تضع البوابة علامة عليه. - -```bash -forge atlas build # index this repo's symbols → .forge/atlas.json -forge atlas has useAuth # "not found" = likely hallucinated -``` - -الأطلس (atlas) هو JSON عادي عن قصد — يقرأ Codex وCursor وGemini وAider ملف -`.forge/atlas.json` عبر CLI أو `jq` العادي، دون أي اعتماد على MCP. - -## المواصفة-كعقد — `forge spec` - -ثبِّت السلوك في مواصفة واكتشف الانحراف عنها: - -```bash -forge spec init # scaffold an OpenSpec contract -forge spec lock # lock the current spec as the contract -forge spec check # report drift against the locked contract -``` - -## بوابة المهارات — `forge scan` - -قبل تثبيت مهارة أو خادم MCP، افحصه بحثًا عن الحقن، أو تنفيذ الشيفرة عن بُعد (RCE)، -أو تسريب البيانات: - -```bash -forge scan -``` - - - الفحص النظيف **ليس شهادة أمان.** لا تصطاد الاستدلالات المدمجة سوى أشكال الهجمات المعروفة - (الحرجة) وعدد قليل من الأنماط عالية الخطورة؛ اجتيازها يعني _"لم يُكتشف توقيع حرج"_، - وليس _"آمن للتثبيت"_. راجع دائمًا المصدر، والأذونات، ومصدر الحزمة، وسلوك الشبكة بنفسك. - النتيجة عالية الخطورة **high** لا تُوسم آمنة رغم أنها لا تحجب فعليًا. الماسح الخارجي - اختياري ولا يجري أي استدعاء شبكي إلا إذا مكّنتَه. - - -## التصليب — `forge harden` - -وصِّل ضوابط الأمان التي تُبقي الأسرار والتغييرات غير الآمنة خارج المستودع: - -```bash -forge harden # gitleaks pre-commit + sandbox settings -``` - -## بوابة على مستوى الالتزام — `forge precommit` - - - `forge precommit` هي بوابة على مستوى الالتزام (commit) — تُشغّل الحد الأدنى للتحقق - وقت الالتزام حتى يُصطاد العمل الجزئي أو غير المُتحقَق منه قبل أن يهبط. - - -## بوابة الإكمال — الدليل الاختباري مطلوب - -لم تعُد بوابة إكمال مسار Stop (راجع -[الذاكرة عبر الجلسات](/ar/concepts/cross-session-memory)) تقبل تسليم الوكيل دليلًا على -اكتمال تغييرات الشيفرة. بالنسبة لأي جلسة لمست شيفرة المصدر، تشترط البوابة **دليلًا -اختباريًا حقيقيًا**: - -- ملف اختبار مُعدَّل في فرق الجلسة، **أو** -- تشغيل ناجح طازج لـ `forge verify` مُسجَّل مقابل التغييرات الحالية. - -لا تكفي لقطة `forge handoff` وحدها لاجتياز البوابة — فهي تُسجّل النية، لا التحقق. إن -غاب كِلا الدليلَين، تحجب البوابة مرة واحدة مع قائمة إصلاح: - -```bash -forge verify # produce the test evidence -forge handoff "" --next "" # then snapshot the session -``` - -الجلسات التي لا تمس الشيفرة — كالتغييرات على التوثيق فقط، أو الإعدادات فقط، وغيرها — -لا تتأثر؛ فمطلب الدليل الاختباري يُطلَق فقط حين يُغيّر فرق الجلسة الشيفرة فعلًا. - -## فحوصات واجهة المستخدم — `forge uicheck` - -فحوصات UI حتمية، دون LLM ودون لقطات شاشة لأول ثلاث عدسات: - -```bash -forge uicheck contrast # WCAG contrast ratio -forge uicheck fingerprint # deterministic design fingerprint -forge uicheck design # slop-distance + conformance gate -forge uicheck visual # Playwright-rendered check (opt-in tier) -``` - -قرن ذلك مع `forge taste` لاختيار اتجاه بصري واحد (brutalist، corporate، -editorial، minimalist، playful) ومعايرة عتبات بوابة `design`. diff --git a/mintlify/ar/guides/radar-deps.mdx b/mintlify/ar/guides/radar-deps.mdx deleted file mode 100644 index 5455b2d..0000000 --- a/mintlify/ar/guides/radar-deps.mdx +++ /dev/null @@ -1,65 +0,0 @@ ---- -title: "الحفاظ على تحديث التبعيات باستخدام radar" -description: "يجمع forge radar تبعياتك في حلقات حداثة (currency rings) بحيث تظهر التبعيات القديمة أو المنحرفة قبل أن تسبب مشكلات." ---- - - - `forge radar` متاح. يصف هذا الدليل كيف يتناسب مع انضباط تحديث التبعيات القائم؛ - شغّل `forge --help` للتأكد من توفره في نسختك المثبتة. - - -من قواعد الهندسة في Forge: _قبل إضافة تبعية، تحقق من الخيار الأفضل الحالي من مصادر حية، -وفضّل ما يستخدمه المشروع بالفعل._ يجعل `forge radar` الحالة القائمة لتبعياتك مرئية بحيث -تكون لهذه القاعدة بيانات تدعمها. - -## الفكرة: حلقات الحداثة - -يجمع `forge radar` تبعيات المشروع في **حلقات حداثة** متمركزة بحسب مدى حداثة كل واحدة — -من المحدَّثة في المركز إلى القديمة أو المنحرفة عند الحافة. قراءة الحلقات طريقة سريعة للإجابة -عن سؤال "ما الذي تركناه ينحرف؟" دون تدقيق كل حزمة يدويًا. - -```bash -forge radar -``` - -## من أين تأتي قائمة التبعيات - -يبني radar على قراءة البيان (manifest) نفسها التي تدعم `forge stack`، والذي يكتشف -المكدس الحقيقي للمستودع من بيانات تبعياته: - -```bash -forge stack # languages, frameworks, package managers, real test commands -``` - -ولأن الاكتشاف قائم على البيانات وآمن الفشل عبر الأنظمة البيئية (`package.json`، -`pyproject.toml`، `go.mod`، `Cargo.toml`، `Gemfile`، `composer.json`، `pom.xml` / -`build.gradle`، `*.csproj`)، يستطيع radar الاستدلال بشأن الحداثة لنفس مجموعة البيانات -التي يفهمها `stack`. - -## استخدامه في الحلقة - - - - شغّل `forge radar` لترى أي التبعيات تنحرف بالفعل قبل أن تضيف واحدة أو ترقّيها. - - - إذا كانت هناك تبعية قادرة وحديثة موجودة بالفعل في حلقة داخلية، فأعد استخدامها بدلًا - من إضافة أخرى — أصغر تغيير مناسب هو الفائز. - - - عندما ترقّي تبعية أو تستبدلها، سجّل السبب: - ```bash - forge decide "bump to — " - ``` - حتى تقرأ الجلسات المستقبلية الاختيار بدلًا من إعادة التداول فيه. - - - - - يُبلّغ radar عن الحداثة؛ لا يقوم بالترقية نيابةً عنك. عامِل حلقاته كمُدخَل استشاري لقرار - بشري — وتحقق من أي ترقية باختبارات المستودع الحقيقية (`forge verify`) قبل اعتبارها منجزة. - - - - بعد ترقية تبعية، شغّل بوابات الجودة — `forge verify` و `forge precommit`. - diff --git a/mintlify/ar/guides/team-memory.mdx b/mintlify/ar/guides/team-memory.mdx deleted file mode 100644 index c225a89..0000000 --- a/mintlify/ar/guides/team-memory.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "ذاكرة الفريق باستخدام السجل" -description: "اطوِ سجل زميلك في الفريق دون تعارضات فوق git العادي — لا خادم، ولا خدمة مزامنة، فقط ملفات تتلاقى بأي ترتيب." ---- - -كل ما تتعلمه الركيزة (substrate) — دروس cortex، وحقائق `forge remember`، وآثار إعادة الاستخدام -المُتحقَّق منها — يهبط كادعاءات مُعنونة بالمحتوى في سجل أصلي لـ git (`.forge/ledger/`) مُصمَّم -ليُدمج دون تعارضات. لا خادم ولا خدمة مزامنة؛ إنها مجرد ملفات في git. - -## ذاكرة الفريق في ثلاثة أوامر - - - - ```bash - forge init - ``` - من بين أشياء أخرى، يُصدر هذا الأمر قاعدة دمج الاتحاد في `.gitattributes` التي يحتاجها السجل. - - - تُلقي دروس cortex وحقائق `forge remember` بظلال ادعاءات في السجل أثناء عملك — - لا شيء إضافي يجب تشغيله. - - - ```bash - git pull && forge ledger merge - ``` - بأي ترتيب — الدمج خالٍ من التعارضات. - - - -## لماذا لا يمكن أن يتعارض - -بايتات الادعاء هي دالة صرفة من `(kind, body, scope)`، لذا تحسب كل نسخة الهوية نفسها لنفس -المعرفة. الدمج هو شبكة نصف اتصال (join-semilattice) — مُختبَرة بخصائص تُثبت أنها تبادلية، -وتجميعية، وعديمة القوة (idempotent) — لذا تتلاقى سجلات زميلين إلى الحالة نفسها بغض النظر -عمن يزامن أولًا. - -```mermaid -flowchart LR - A["your ledger"] <-->|"git union-merge · conflict-free"| B["teammate ledger"] - A --> M["merged read view"] - B --> M - M --> R["recall list · lesson inject · brain index"] -``` - - - المعرفة المتطابقة التي تُسَك بشكل مستقل تتلاقى إلى ادعاء **واحد** مع الحفاظ على كل مؤلف - في مصدرها (provenance). - - -## الثقة والمصدر - -لا تتحرك الثقة إلا بواسطة أدوات تحقق مستقلة — اختبارات، وCI، وقبول/تراجع بشري — لذلك -فإن استيراد سجل زميل لا يثق بملاحظاته على نحوٍ أعمى؛ بل يستورد _أدلته_. - -```bash -forge ledger blame # who minted a claim, every oracle outcome, per-author trust -forge ledger stats # the merged view, by kind and trust level -forge ledger verify # confirm every claim is in normal form -``` - -## إعادة الاستخدام عبر الفريق - -بمجرد أن تكون شيفرة زميلك المُتحقَّق منها في السجل المدموج، يمكنك إعادة استخدامها مع دليلها: - -```bash -forge reuse query "" -``` - -الإصابة تشير إلى شيفرة عاملة ومؤكَّدة بالاختبارات و`forge ledger blame` التي تُثبتها — -أعد استخدامها بدلًا من إعادة توليدها. - - - تُحفظ الادعاءات الخاملة للتدقيق ولا تُحذف أبدًا؛ المعرفة غير المُراجَعة تضمحل نحو _عدم اليقين_، - لا نحو الحذف. السجل مسار أدلة، وليس ذاكرة تخزين مؤقت يمكنك أن تفقدها بصمت. - diff --git a/mintlify/ar/guides/zero-config-onboarding.mdx b/mintlify/ar/guides/zero-config-onboarding.mdx deleted file mode 100644 index 72f0878..0000000 --- a/mintlify/ar/guides/zero-config-onboarding.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: "إعداد موجَّه بأدنى تهيئة" -description: "خمس دقائق لتصبح منتجًا: ثبِّت مرة واحدة، اضبط المستودع مرة، نفّذ مهمة، وشاهد السجل يبدأ في الإنتاجية من اليوم الثاني — موجَّه، بأدنى تهيئة، وليس بلا لمس." ---- - -يهدف Forge إلى **إعداد موجَّه بأدنى تهيئة** — عادةً ما يكون المستودع الجديد منتجًا في نحو -خمس دقائق. ثبِّت مرة واحدة، اضبط المستودع مرة، نفّذ مهمة، ثم يبدأ السجل في الإنتاجية من -اليوم الثاني. (إنه بأدنى تهيئة، وليس بلا تهيئة: لا تزال تحتاج إلى تثبيت CLI، وتشغيل -`forge init` في كل مستودع، وبعض المسارات تفترض وجود Bash وGit و`jq`.) - -```mermaid -flowchart TD - I["forge init"] --> Cfg["every tool configured from one source"] - Cfg --> Work["you work as usual"] - Work --> Gate["substrate checks each task · ask first? · which model? · what breaks?"] - Gate --> Edit["agent edits, with guardrails"] - Edit --> Learn["cortex learns from corrections"] - Learn -.->|next task is smarter| Work -``` - -## 1. التثبيت (مرة واحدة) - -المسارات الموصى بها لا تحتاج إلى رمز مصادقة ولا إلى استنساخ: - - - -```bash Plugin -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit -``` - -```bash CLI -npm install -g @codewithjuber/forgekit -``` - - - -```bash -forge doctor # everything green? -``` - -## 2. اضبط مستودعًا (مرة واحدة لكل مستودع) - -```bash -cd ~/your-project -forge init # emits AGENTS.md, CLAUDE.md, .gemini/settings.json, .aider.conf.yml … -``` - -الآن يقرأ Claude Code وCodex وCursor وGemini وAider وCopilot وWindsurf وZed وContinue -**نفس** القواعد — كل واحد منها من ملفه الأصلي. غيّر قاعدة لاحقًا بتحرير `source/rules.json` -(أو بإفلات `.forge/rules.json` خاص بالمستودع)، ثم شغّل `forge sync`. - -## 3. استخدم الركيزة الإدراكية - -```bash -forge substrate "" # ask/route/impact/scope/reuse/context/memory/verify in one pass -forge substrate "" --json -forge impact # the blast radius on its own -``` - -إذا قال `forge substrate` `ASK FIRST`، فاسأل الأسئلة الواردة قبل التعديل. - -## 4. استخدم الإضافات - -```bash -forge atlas build # index this repo's symbols → .forge/atlas.json -forge atlas query useAuth # where is it defined? -forge atlas has useAuth # does it exist? "not found" = likely hallucinated -forge recall add "db port" "Postgres is on 5433 here, not 5432" -forge catalog # the Start-Here index of everything -``` - -## 5. اليوم الثاني: السجل يتعلم - -كل ما تعلمته الركيزة في اليوم الأول — دروس cortex، والحقائق المتذكَّرة، والشيفرة المُتحقَّق منها — -هبط كادعاءات في `.forge/ledger/`. - -```bash -forge ledger stats # what the repo knows, by kind and trust level -forge ledger blame # who minted a claim, every oracle outcome -forge reuse query "" # verified code you already have -``` - - - التالي: اطوِ سجل زميلك في الفريق دون تعارضات فوق git العادي. - diff --git a/mintlify/ar/installation.mdx b/mintlify/ar/installation.mdx deleted file mode 100644 index 5376b15..0000000 --- a/mintlify/ar/installation.mdx +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: "التثبيت" -description: "ثلاثة أبواب أمامية لشجرة واحدة: سوق الإضافات، وتثبيت npm العام، وتثبيت github: دون سجل — إضافةً إلى إعداد المساهمين بالروابط الرمزية." ---- - -يتّبع Forge تصميم **شجرة واحدة وثلاثة أبواب أمامية**: بيان المُلحق، والمُثبِّت المُقوّى، -وثنائي npm العام، جميعها تشير إلى الشجرة نفسها `global/` + `source/`. اختر القناة -الملائمة لأداتك. - -## اختر قناة - - - - لأداتَي Claude Code وCodex. تُوصَل الحواجز تلقائيًا؛ لا شيء يُدمج. - - - لأي أداة. واجهة سطر أوامر `forge` من سجل npm العام. - - - لا حاجة إلى سجل — ثبّت مباشرة من المستودع. - - - استنساخ + `npm link`، أو `bash install.sh` لإعداد الروابط الرمزية. - - - -## المتطلبات - -- **Node.js >= 20** -- **صفر تبعيات وقت التشغيل** — كل شيء مبني داخل Node. الطبقات الاختيارية - (تضمينات `FORGE_EMBED`، وPlaywright لأمر `uicheck visual`) اختيارية ولا تضيف أي - تبعيات مطلوبة. - -## سوق المُلحقات - -المسار الموصى به لأداتَي Claude Code وCodex لا يحتاج رمزًا ولا استنساخًا: - -```bash -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit -``` - -يوصل المُلحق الحواجز عبر `${CLAUDE_PROJECT_DIR}` بحيث تعمل بوّابتا ما قبل الفعل والإكمال -بشكل ضمني. - -## npm العام - -لأي أداة، من npm العام: - -```bash -npm install -g @codewithjuber/forgekit -forge doctor # everything green? -``` - -## تثبيت github: دون سجل - -```bash -npm install -g github:CodeWithJuber/forgekit -``` - -## مساهم / تطوير محلي - - - -```bash npm link -git clone https://github.com/CodeWithJuber/forgekit.git -cd forgekit -npm link -``` - -```bash install.sh (symlink setup) -git clone https://github.com/CodeWithJuber/forgekit.git -cd forgekit -bash install.sh -``` - - - -المُثبِّت مُقوّى: عديم الأثر، ومبني على الروابط الرمزية، مع نسخة احتياطية، ودون -`curl | sh`. - -## التحقّق - -مهما كانت القناة التي استعملتها، تأكّد من التثبيت: - -```bash -forge doctor # tools, guards, MCP auth, config drift, update status -``` - - - يُظهر `forge doctor` أيضًا إشعارًا غير مُلحّ بشأن "التزامات متأخرة عن المنبع" لعمليات - استنساخ git. اضبط `FORGE_NO_UPDATE_CHECK=1` لإسكاته. كل مسار يفشل بلطف — دون - اتصال أو رأس منفصل يُبلَّغ عن "غير معروف"، لا خطأ. - - -## إبقاء Forge محدَّثًا - -```bash -forge update --check # report whether a newer version is available -forge update # apply the update (git checkout or npm/copy install) -forge update --to # pin or downgrade to a specific version -``` - - - انتقل إلى البدء السريع لتشغيل `forge init` وأول فحص للركيزة. - diff --git a/mintlify/ar/introduction.mdx b/mintlify/ar/introduction.mdx deleted file mode 100644 index 2008216..0000000 --- a/mintlify/ar/introduction.mdx +++ /dev/null @@ -1,134 +0,0 @@ ---- -title: "Forge: الركيزة المعرفية لوكلاء البرمجة بالذكاء الاصطناعي" -description: "Forge هو الركيزة المعرفية التي يفتقدها كل نموذج عديم الحالة — الذاكرة، والاستشراف، وحواجز الأمان — يُقدَّم كإعداد أصلي لكل وكيل برمجة يعتمد على الذكاء الاصطناعي." ---- - -**دماغ واحد لكل وكيل برمجة يعتمد على الذكاء الاصطناعي.** النموذج اللغوي الكبير عديم -الحالة: نافذة سياق واحدة، تُمسح مع كل استدعاء. ليس لديه أي ذاكرة بما تعلمه فريقك، ولا -استشراف لما قد يكسره أي تعديل، ولا حواجز أمان مُنفَّذة. إن Forge -(`@codewithjuber/forgekit`) هو **الركيزة المعرفية** — الطبقة التي تعمل -_قبل_ أن يعدّل النموذج الشيفرة، والتي تُوفّر ذاكرةً مرجعية للأدلة وعنوانها محتواها (نُطلق -عليها اسم "الذاكرة الحاملة للإثبات")، واستشرافًا استدلاليًا للأثر، وحواجز أمان مُنفَّذة — -وكذلك **مُصرِّف إعدادات عابر للأدوات** يوصل هذا الدماغ كإعداد أصلي إلى كل الأدوات -دفعة واحدة. أعمق تكامل مُختبَر هو مع Claude Code؛ أما البقية فتحصل على إعداد أصلي -وأدوات MCP، مع تجربة ميدانية أقل. - - - - ذاكرة حاملة للإثبات تدوم عبر الجلسات وبين أعضاء الفريق. كل درس، وحقيقة، وإعادة استخدام - مُتحقَّق منها هي ادعاء يحمل دليله معه. - - - نصف قطر الانفجار لأي تعديل — مجموعة الملفات المتوقع أن يمسّها، مقروءةً من رسم - الشيفرة، بما في ذلك الملفات المُترابطة التي لم تسمّها. - - - خطّافات حتمية تُنفّذ القواعد التي لا يجوز للنموذج أن يخالفها أبدًا. تصمد بعد ضغط - السياق بطريقة لا يصمد بها النص الطليق في ملف إعدادات. - - - -## المشكلة - -النموذج اللغوي الكبير عديم الحالة — نافذة سياق واحدة، تُمسح مع كل استدعاء. - -- **لا يملك أي ذاكرة** بما تعلمه فريقك سابقًا. -- **لا يملك أي استشراف** لما سيكسره أي تعديل. -- **لا يملك أي حواجز أمان مُنفَّذة** — القواعد النصية تُنسى بعد الضغط. - -وكل أداة تريد ملف إعدادات خاصًا بها (`CLAUDE.md`، `AGENTS.md`، `.cursor/rules`، -`GEMINI.md`، MCP…). إن Forge هو الركيزة المعرفية التي تُوفّر الأشياء الثلاثة المفقودة، -والمُصرِّف الذي يوصلها إلى كل أداة من مصدر واحد. - -## الأطروحة - -لا يستطيع النموذج أن يتعلم من قاعدة شيفرتك بين الاستدعاءات: أوزانه مُجمَّدة وذاكرته -العاملة تُمسح بعد كل استجابة. لا يمكن حَقن الذاكرة والاستشراف والتحقق الذاتي فيه عبر -الطلبات — يجب توفيرها من _الخارج_. تلك الطبقة الخارجية هي الركيزة المعرفية. رياضيًا، -الاستدلال هو دالة ثابتة `y = f(x)` بلا حالة بين الاستدعاءات؛ وForge هو الحالة. - - - - اكتب قواعدك وإعدادات الركيزة الافتراضية في مصدر واحد قانوني - (`source/rules.json`، `source/substrate.json`، `source/mcp.json`). - - - يقوم `forge sync` بتصريف هذا المصدر إلى الإعداد الأصلي لكل أداة — تسع أدوات برمجة - مدعومة بالذكاء الاصطناعي إضافةً إلى MCP — مع ترويسة تجزئة للمحتوى، فيصير الانحراف - قابلًا للكشف وإعادة التشغيل بلا أثر. - - - يُشغّل `forge substrate ""` تمريرًا حتميًا واحدًا قبل الفعل: الافتراضات، - والتوجيه، وإعادة الاستخدام، والسياق، ونصف قطر الانفجار، والنطاق، ومرساة الهدف. - - - فقط الأدوات المستقلة — الاختبارات وCI وقبول/تراجع الإنسان — هي التي تحرّك ثقة - الذاكرة، بحيث يتلاشى الدرس الخاطئ بدلًا من أن يتحجّر. - - - -## ماذا تحصل - -- **ذاكرة تدوم عبر الجلسات وبين أعضاء الفريق.** كل درس، وحقيقة، وإعادة استخدام - مُتحقَّق منها هي _ذاكرة حاملة للإثبات (PCM)_ — اسمنا للذاكرة المرجعية للأدلة والمعنونة - بمحتواها: ادعاء يحمل مراجع لأدلته ولا يُوثَق به إلا عندما ترفع الأدوات المستقلة ثقته - فوق حدٍّ أدنى. "الإثبات" هو مسار الأدلة، لا برهان صوري. -- **استشراف قبل أن تكسر الأشياء.** اسأل "ماذا يكسر تغييرُ `verifyToken`؟" - واحصل على نصف قطر الانفجار من رسم الشيفرة، بما في ذلك الملفات المترابطة التي لم تسمّها. -- **حواجز أمان لا يمكن نسيانها.** خطّافات حتمية تُنفّذ المسارات المحمية، - وميزانيات التكلفة، وكشف الحلقات الهالكة — وتصمد بعد ضغط السياق. -- **عمل يكتمل من طرف إلى طرف.** بوّابة إكمال تحجب "تم" مرة واحدة في كل جلسة - عند تحرّك الشيفرة دون أن يتبعها توثيق أو أثر حالة، مع قائمة الإصلاح كإجابة. -- **إعداد واحد لتسع أدوات.** اكتب قواعدك مرة واحدة؛ يُصدر Forge الإعداد الأصلي - لكل أداة، إضافةً إلى MCP لأدوات Roo وVS Code. صفر تبعيات وقت التشغيل — CLI واحد - بلغة Node، وملفات عادية في git، دون خادم. - -## أي أدوات يُغذّي Forge؟ - -يُصدر Forge إعدادات لـ **تسع أدوات**، إضافةً إلى خادم MCP لأداتَي Roo Code وVS Code: -Claude Code، وCodex، وCursor، وGemini، وAider، وCopilot، وWindsurf/Devin، وZed، -وContinue. تقرأ كلٌّ منها القواعد نفسها من ملفها الأصلي. - -خادم MCP الوحيد الموصول افتراضيًا هو خادم Forge نفسه (`src/cortex_mcp.js`) — فحوصات -الركيزة وقراءات الذاكرة. أما خوادم MCP الطرف الثالث مثل `context7` فهي **اختيارية** -ولا تهبط على القرص إلى أن تُشغّل [`forge integrations add --yes`](/ar/cli/config#forge-integrations). - -## الحدود الصادقة - -يُعلن Forge سقفه في كل مكان. - - - إن Forge **يُقلّل ولا يُلغي** انحراف القواعد. هو طبقة شفافية وموثوقية، - لا بديل للاختبارات أو المراجعة أو الحكم البشري. - - -- **الحواجز تُنفّذ فقط ما يمكن التعبير عنه كخطّاف** (المسارات، والتنسيق، وحجم الفرق، - والميزانية). القواعد الدلالية ("فضّل الأسلوب الدالّي") تبقى نصًا وقد تُتجاهل أحيانًا. -- **التحقق يُقلّل ولا يشهد.** يُقلّص الفريق المُتحقِّق وعَلَم الرموز المُهلوَسة عبء - المراجعة؛ لكنها لا تُثبت صحة الشيفرة. -- **لا تعلّم على مستوى الأوزان.** `recall` / `cortex` ذاكرة ملفات وطلبات فقط — - لا تعلّم مُعزَّز ولا ضبط دقيق. -- **رسم الأثر تقريبي بواسطة regex** — متحفّظ لا رسم استدعاء دقيق. -- **الاختبارات وتصحيحات الإنسان تفوز دائمًا.** - - - إن Forge في مرحلة **بيتا**. النواة (`init`، `sync`، `substrate`، `impact`، `ledger`، - والحواجز) مُختبَرة ومستخدمة يوميًا؛ قد تتغيّر بعض العلامات قبل `1.0`. - - -## الخطوات التالية - - - - ثبِّت، وشغّل `forge init`، ومرِّر مهمتك الأولى عبر الركيزة. - - - المُصرِّف رباعي الطبقات، والذاكرة الحاملة للإثبات، وبوّابة ما قبل الفعل. - - - كل أمر مُصنَّف حسب المجموعات: Core وMemory وSubstrate وQuality وConfig. - - - ادمج سجل زميلك في فريقك بلا تعارضات، عبر git عادي. - - diff --git a/mintlify/ar/quickstart.mdx b/mintlify/ar/quickstart.mdx deleted file mode 100644 index 7790b69..0000000 --- a/mintlify/ar/quickstart.mdx +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "البدء السريع" -description: "ثبّت Forge، وأصدر إعداد كل أداة من مصدر واحد، وشغّل أول بوّابة قبل الفعل — في نحو 60 ثانية." ---- - -انتقل من الصفر إلى مستودع مُعدّ وأول فحص للركيزة في حوالي دقيقة. - -## 1. التثبيت - - - -```bash Plugin (Claude Code / Codex) -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit -``` - -```bash npm (any tool) -npm install -g @codewithjuber/forgekit -``` - -```bash No registry -npm install -g github:CodeWithJuber/forgekit -``` - - - -المسار عبر المُلحق هو الموصى به لأداتَي Claude Code وCodex — تُوصَل الحواجز تلقائيًا -ولا يوجد ما يُدمج. راجع [التثبيت](/ar/installation) للمصفوفة الكاملة، بما في ذلك إعداد -التطوير بالروابط الرمزية. - -## 2. إعداد المستودع - - - - ```bash - cd ~/your-project - forge init - ``` - يُصدر هذا `AGENTS.md`، و`CLAUDE.md`، و`.gemini/settings.json`، و`.aider.conf.yml`، - والباقي — إضافةً إلى قاعدة الدمج الاتحادي في `.gitattributes` التي يحتاجها السجل. - الآن تقرأ Claude Code، وCodex، وCursor، وGemini، وAider، وCopilot، وWindsurf، وZed، - وContinue **القواعدَ نفسها**، كلٌّ من ملفها الأصلي. - - - ```bash - forge doctor - ``` - فحص نجاح/إخفاق للأدوات المثبتة، والحواجز، ومصادقة MCP، وانحراف الإعدادات. - - - عدّل `source/rules.json` (أو ضع `.forge/rules.json` خاصًا بالمستودع)، ثم أعد التصريف: - ```bash - forge sync - ``` - الأمر `sync` عديم الأثر — يعيد كتابة ما تغيّر فقط. - - - -## 3. تشغيل بوّابة ما قبل الفعل - -الركيزة هي الطبقة التي تعمل _قبل_ أن يعدّل النموذج الشيفرة. أمر واحد يُشغّل البوّابة -بأكملها: - -```bash -forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" -# → assumption verdict · cheapest capable model · predicted blast radius -# (including files you didn't name) · scope clusters · verification checklist -``` - - - في Claude Code تعمل الركيزة تلقائيًا **على كل طلب** عبر خطّاف - `UserPromptSubmit` — إرشادية فقط، وصامتة عند المهام النظيفة. تحصل كل أداة أخرى على - قاعدة إعداد أصلية إضافةً إلى 19 أداة MCP يمكنها استدعاؤها بنفسها. - - -إذا قال `forge substrate` `ASK FIRST`، اسأل الأسئلة المُرجَعة قبل التعديل. اقرأ الملفات -المتوقع تأثرها — نصف قطر الانفجار — قبل أي تغيير مُعدِّل. - -```bash -forge substrate "" --json # machine-readable verdict -forge impact # the blast radius on its own -``` - -## 4. استكشف الإضافات - -```bash -forge atlas build # index this repo's symbols → .forge/atlas.json -forge atlas query useAuth # where is it defined? (cheaper than grep-and-read) -forge atlas has useAuth # does it exist? "not found" = likely hallucinated -forge recall add "db port" "Postgres is on 5433 here, not 5432" -forge catalog # the Start-Here index of everything -``` - -## 5. اليوم الثاني: السجل يتعلّم - -كل ما تعلمته الركيزة في اليوم الأول أُودع كادعاءات في `.forge/ledger/`. هذه هي -الذاكرة الحاملة للإثبات — والآن يبدأ عائدها: - -```bash -forge ledger stats # what the repo knows, by kind and trust -forge ledger blame # who minted a claim, every oracle outcome -forge reuse query "" # verified code you already have -``` - - - اقرأ كيف تُركّب بوّابة ما قبل الفعل مراحلها في حكم واحد. - diff --git a/mintlify/cn/changelog/overview.mdx b/mintlify/cn/changelog/overview.mdx deleted file mode 100644 index cbe01cb..0000000 --- a/mintlify/cn/changelog/overview.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "更新日志" -description: "了解 Forge 的最新动态、功能改进与行为变更，帮助你及时掌握每次发布中影响验证、会话与交接流程的关键更新。" ---- - - - -## 更新内容 - -**`forge verify --deep` 现在会报告四态结果。** 多视角共识运行不再折叠为二元的通过/失败。你会看到 `PASS`、`FAIL`、`INCOMPLETE` 或 `NOT_CONFIGURED` 中的其中一个，因此停滞的视角或未配置的仓库不会悄悄被视为通过。只有 `PASS` 才算已验证，并且 `PASS` 现在还要求底层 `forge verify` 测试状态也为 `PASS` —— 绿色的深度运行永远无法覆盖红色的基础运行。 - -参见 [质量命令](/cn/cli/quality) 和 [验证门](/cn/concepts/verification-gates)。 - -**完成门要求对代码变更提供测试证据。** 对于任何涉及源代码的会话，Stop 路径的完成门不再单独接受 `forge handoff` 快照。你需要在会话的差异中包含测试文件，或针对当前变更提供一次新鲜且通过的 `forge verify`。仅文档、仅配置以及其他非代码类会话不受影响。 - -当该门拦截时，修复清单现在会以 `forge verify` 为首，以便在生成交接快照之前先记录证据。参见 [跨会话记忆](/cn/concepts/cross-session-memory)。 - -**更清晰地定位钩子与护栏。** Forge 的自动钩子是 Claude Code 专属的，并且——与其他所有建议性信号一样——在你通过 `FORGE_ENFORCE=1` 显式启用之前默认关闭。这些护栏是纵深防御，而不是安全沙箱。运行时本身没有任何变化；只是文档与 CLI 文案与该工具的实际行为保持一致。参见 [CLI 概览](/cn/cli/overview) 和 [预操作门](/cn/concepts/pre-action-gate)。 - -## 修复 - -**密钥脱敏器现在会保留结构化的工具输出。** 像 Bash、Read 和 Grep 这样的内置工具会返回结构化对象，而先前的脱敏器会把这些响应字符串化——这意味着 Claude Code 会静默丢弃改写结果，未脱敏的输出仍然可见。脱敏器现在会递归遍历响应：字符串就地清洗，数组和对象保留其键和形状，非字符串的叶子节点原样透传。纯字符串响应的脱敏结果与之前逐字节一致，而没有任何内容需要脱敏的响应根本不会发出改写。 - -**`FORGE_GUARD_STRICT=1` 的退出状态不再被吞掉。** 脱敏器的 shell 包装脚本此前会强制以干净状态退出，将严格模式的失败码从 Claude Code 中隐藏起来，导致 `DEGRADED` 信号从未浮现。子进程的退出状态现在会端到端地透传，因此严格模式的 stderr 反馈才能真正送达你。请注意，该钩子是在工具已经执行之后运行的——严格模式让脱敏器的降级变得显眼，但在调用运行之前将其拦截，是 [预操作门](/cn/concepts/pre-action-gate) 的职责。 - - diff --git a/mintlify/cn/cli/config.mdx b/mintlify/cn/cli/config.mdx deleted file mode 100644 index 0a57be0..0000000 --- a/mintlify/cn/cli/config.mdx +++ /dev/null @@ -1,161 +0,0 @@ ---- -title: "Config 命令" -description: "提供方、成本、仪表盘、品牌、atlas、技术栈和可选 MCP 集成：config、cost、dash、brand、atlas、stack、tools、integrations。" ---- - -Config 分组涵盖提供方、可观测性、代码图和技术栈探测。 - -## `forge config` - -提供方配置 —— 显示 / 切换 / 添加提供方，设置默认模型。 - -```bash -forge config # show current config -forge config switch -forge config add -``` - -## `forge cost` - -通过实测的阶段系数得到真实的每日开销。 - -```bash -forge cost # real per-day spend -forge cost --stages # measured per-stage cost factors -``` - - - 只报告**实测的阶段** —— 一个没有事件记录的阶段会显示"no data"，绝不会给出 - 一个默认值。 - - -## `forge dash` - -跑在账本、指标和爆炸半径之上的本地仪表盘。 - -```bash -forge dash # localhost-only (default port 4242) -``` - -## `forge brand` - -打印当前的品牌 token 映射。 - -```bash -forge brand -``` - -品牌以一份 token 存储在（`brand.json`）里；换品牌就是一次编辑。 - -## `forge atlas` - -构建 / 查询代码图。 - -```bash -forge atlas build [path] # walk the tree → .forge/atlas.json -forge atlas query "what calls Z" -forge atlas has # hallucinated-symbol check -``` - -atlas 是纯 JSON —— 任何工具都能读，不需要 MCP。 - -## `forge stack` - -从本仓库的清单文件里探测它真实的技术栈。 - -```bash -forge stack -``` - -会读取 `package.json`、`pyproject.toml`、`go.mod`、`Cargo.toml`、`Gemfile`、 -`composer.json`、`pom.xml` / `build.gradle` 以及 `*.csproj`，报告语言、 -框架、包管理器和仓库**真正**的测试命令 —— 这些会喂给 -基底的验证清单。 - -## `forge report` - -生成本仓库 Forge 状态的静态 HTML 报告 —— 把账本、指标和爆炸 -半径渲染成一个可以分享或归档的、自包含的文件。 - -```bash -forge report -``` - -## `forge tools` - -选择本仓库的主 AI 编码工具，并接通对应的 `.gitignore` 条目，让 -生成的配置和 `.forge/` 产物在你的这套配置里被正确忽略。 - -```bash -forge tools -``` - -## `forge integrations` - -按需接入（opt-in）的第三方 MCP 服务器（例如 `context7`），以非破坏性的方式管理， -覆盖 Forge 为之输出配置的每一个工具 —— Claude Code、Codex、Cursor、Gemini、Continue -以及其他所有工具。 - -第三方 MCP 服务器**默认不安装**。在你执行 `forge integrations add --yes` -之前，什么都不会落到磁盘上。 - -```bash -forge integrations # list opt-in servers with package + purpose -forge integrations add # dry-run: prints package, network, files it would touch -forge integrations add --yes # apply — write MCP config for every tool -forge integrations add --yes --adopt # also claim a same-name entry you already configured -forge integrations remove # reverse the add — deletes only forge-owned entries -``` - -### `add` 会写什么 - -`add --yes` 从一份规范的 spec 出发，把这个服务器写入每个工具原生的 MCP 配置： - -- `.mcp.json`（Claude Code） -- `.cursor/mcp.json`（Cursor） -- `.gemini/settings.json`（Gemini） -- `.codex/config.toml` —— 作为一个 `# forge:managed:` 代码块，通过逐字节比对 - 来刷新 -- `.continue/mcpServers/.yaml` —— 每个被管理的服务器一个带 forge 标记的 YAML -- 以及 Forge 为之输出配置的其他工具 - -已安装的集合记录在 `.forge/forge.config.json` 的 `mcp.integrations` 下，因此之后每一次 -`forge sync` 都会重新输出同一批服务器。stop-hook 的自动同步会对整份配置文件做逐字节 -比对，所以对该文件的手工编辑会被检测到并被修复。 - -### `--adopt` 的语义 - -如果一个同名的服务器已经存在于某个工具的配置文件里，而且不是 Forge 放进去的，`add` -**不会覆盖它**。它会报告是哪个文件，并给出一个 `--adopt` 提示。加上 `--adopt` 重新 -运行来接管所有权 —— Forge 会把这条记录写到 `.forge/forge.config.json` 的 -`mcp.adopted` 下，从此由 Forge 来管理它。 - -当你之前手工配了某个服务器，现在又想让 Forge 在每个工具之间把它同步保持一致时， -就用 `--adopt`。 - -### `remove` - -`forge integrations remove ` 反转一次 add。它只删除 forge 所拥有的条目、 -代码块和文件 —— 用户自己配的、并且从没 `--adopt` 过的同名服务器会被保留下来。 -连续跑两次 `remove` 是个无操作。 - -```bash -forge integrations remove context7 -``` - -### `.forge/forge.config.json` - -每个仓库的 Forge 状态 —— 这份统一配置里也存着 `primaryTool`、`tools` 和 -`profile` —— 在两个键下记录按需接入的集成： - -```json -{ - "mcp": { - "integrations": ["context7"], - "adopted": [] - } -} -``` - -未知的键在写入时会被原样保留。一个损坏的文件不会被静默丢弃：读取时每个进程会在 -stderr 上告警一次，而写入者会拒绝用默认值覆盖一份无法解析的配置。 diff --git a/mintlify/cn/cli/core.mdx b/mintlify/cn/cli/core.mdx deleted file mode 100644 index c9c326a..0000000 --- a/mintlify/cn/cli/core.mdx +++ /dev/null @@ -1,111 +0,0 @@ ---- -title: "Core 命令" -description: "用 init、sync、doctor、catalog、docs 与 update 引导并维护 Forge 仓库，涵盖 profile、settings、可逆卸载相关标志，无效 profile 中止行为，以及 FORGE_GUARD_STRICT 严格模式的说明。" ---- - -Core 分组用于引导一个仓库并保持它的健康。 - -## `forge init` - -搭起本仓库的配置 —— 从同一份共享来源为每个工具输出配置。 - -```bash -forge init -``` - -输出 `AGENTS.md`、`CLAUDE.md`、`.gemini/settings.json`、`.aider.conf.yml` 等文件 -（外加给 Roo Code 和 VS Code 的 MCP 服务器配置），以及账本所需的 -`.gitattributes` union-merge 规则。 - -`forge init` 还会把 Forge 的 hooks 和 permissions 合并进**全局**的 -`~/.claude/settings.json`，所以它会在写入前先声明这次合并。这次合并是幂等的、 -带标记守护的，永远不会覆盖用户自己的条目。 - -### Init 标志 - -| 标志 | 作用 | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--profile ` | 为本仓库挑选策略 profile。可取 `minimal` 或 `standard`（默认）。无效值会在任何脚手架、`.forge/` 写入或合并动作之前直接中止。 | -| `--no-settings` | 完全跳过对全局 `~/.claude/settings.json` 的合并 —— 只写仓库级配置。 | -| `--remove-settings` | 撤销以往的一次 settings 合并。Forge 形状的 hooks、permissions、statusline 和 `_forge` 标记会被移除；会先写入一份带时间戳的备份，你自己的条目保持不动。也会被 `install.sh --uninstall` 调用。 | -| `--settings-only` | 只合并全局 settings —— 不动仓库。被 `install.sh` 用来接线 hooks 和 permissions。 | - -如果 settings 合并被拒绝或出错，`forge init` 会以 exit 1 失败并把原因写到 stderr， -而不是谎报成功。 - -### 策略 profile - -`--profile` 用来选那套规则集，`forge sync` 会把它编译成每个工具的原生配置。 -只支持两种 profile： - -- **`standard`**（默认）—— 完整包：共享记忆规则、影响分析，以及完整的护栏 hook 集。 -- **`minimal`** —— 更精简的规则集，给小仓库或贡献者 fork 用。 - -旧名字 `web-app`、`backend-service`、`library` 和 `regulated` 都是 `standard` 的 -弃用别名。它们仍然能用：`forge init` 会警告一次、把 `standard` 存下来，已有的、 -仍然拿旧名字的配置会按 standard 同步。新仓库应直接用 `standard`。其它任何值都是 -无效的，会在 Forge 动仓库之前中止。 - -```bash -forge init --profile minimal # leaner ruleset -forge init --no-settings # per-repo only, skip the global merge -forge init --remove-settings # reverse a past global merge -``` - -## `forge sync` - -把规范来源重新编译成每个工具的原生配置文件。 - -```bash -forge sync -``` - -幂等 —— 只重写发生变化的部分。在编辑 `source/rules.json` 或 -仓库级的 `.forge/rules.json` 之后运行它。 - -## `forge doctor` - -对已安装工具、护栏、MCP 认证和配置漂移做健康检查。 - -```bash -forge doctor -``` - -对工具、护栏、MCP 接线、配置漂移和更新状态做通过/失败检查。所有路径 -都是 fail-open。当配置了自定义网关时，**gateway models** 一行会打印 -出解析后的 `tier → model` 映射。 - -## `forge catalog` - -Start Here —— 列出每个工具、crew 和护栏，附上一行原因。 - -```bash -forge catalog -``` - -## `forge docs` - -文档 ↔ 代码漂移。 - -```bash -forge docs check # registry reconcile — commands, env vars, MCP tools, CHANGELOG -forge docs sync # diff-driven stale-docs sweep -``` - - - 当命令、环境变量、MCP 工具或 CHANGELOG 相对代码发生漂移时，`docs check` 会让 CI - 失败。`docs sync` 扫描 diff，并报告 UPDATED / STALE / VERIFIED-UNAFFECTED。 - - -## `forge update` - -跨三种安装方式的自更新。 - -```bash -forge update # apply the update (git checkout or npm/copy install) -forge update --check # report whether a newer version is available -forge update --to # pin or downgrade to a specific version -``` - -所有路径都是 fail-open —— 离线、无上游或 detached HEAD 都会返回"unknown"， -永远不会报错。`FORGE_NO_UPDATE_CHECK=1` 让 doctor 的提示安静下来。 diff --git a/mintlify/cn/cli/memory.mdx b/mintlify/cn/cli/memory.mdx deleted file mode 100644 index b30a8ec..0000000 --- a/mintlify/cn/cli/memory.mdx +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "Memory 命令" -description: "跨会话与团队记忆：cortex、recall、remember、brain、ledger、reuse、handoff 和 decide —— 全部汇聚到那本携带证据的账本。" ---- - -Memory 分组管理跨会话与团队记忆。所有内容都汇聚到 `.forge/ledger/` 下 -那本携带证据的账本。模型细节见 -[Proof-carrying memory](/cn/concepts/proof-carrying-memory)。 - -## `forge cortex` - -自我纠正的项目记忆 —— 从修正中挖掘出来的经验。 - -```bash -forge cortex status # what's been learned -forge cortex why # why a lesson applies here -``` - -## `forge recall` - -管理跨会话的个人记忆。 - -```bash -forge recall list # facts the recall-load guard injects next session -forge recall add "db port" "Postgres is on 5433 here, not 5432" -forge recall consolidate # summarize (advisory, human-reviewable) -``` - -## `forge remember` - -给本仓库的可移植记忆添加一条持久的、可提交进 git 的事实。 - -```bash -forge remember "" -``` - -## `forge brain` - -展示或重建可移植的项目记忆索引。 - -```bash -forge brain # show the index -forge brain --rebuild # rebuild it -``` - -## `forge ledger` - -携带证据的记忆 —— 按内容寻址的声明存储。 - -```bash -forge ledger stats # what the repo knows, by kind and trust level -forge ledger verify # re-check claims are in normal form -forge ledger show # a claim and its evidence -forge ledger blame # who minted it, every oracle outcome, per-author trust -forge ledger query "" # retrieve by relevance -forge ledger ratify # human accept -forge ledger retract # tombstone a claim -forge ledger merge # fold a teammate's ledger in, conflict-free -forge ledger import # back-fill pre-ledger history into the ledger -``` - -加 `--personal` 是每用户的账本。 - -## `forge reuse` - -携带证据的代码缓存 —— 只有当证据依然成立时才会命中。 - -```bash -forge reuse query "" # verified code you already have -forge reuse mint "" --file # add an artifact to the cache -forge reuse stats # cache stats -``` - -## `forge handoff` - -有界的会话快照 —— 重写 `.forge/state.md`，每次会话开始时会重新注入。 - -```bash -forge handoff "" --next "" -``` - -## `forge decide` - -只追加的决策日志 —— 在 `.forge/decisions.md` 里的 `D-####` ADR-lite 条目。 - -```bash -forge decide " — " -forge decide # read the log before re-deciding -``` - -## `forge know` - -把一条事实路由到它正确的存储归宿 —— 决定一条知识应该落在 -`recall`、`remember`/`brain`、决策还是 cortex 经验里，并把它归档到那里。 - -```bash -forge know "" -``` - -## `forge deja` - -相似历史工作查找 —— 从账本中找出与你即将要做的事情 -相似的旧工作，让你复用已有的证据，而不是重新生成。 - -```bash -forge deja "" -``` diff --git a/mintlify/cn/cli/overview.mdx b/mintlify/cn/cli/overview.mdx deleted file mode 100644 index a1c5613..0000000 --- a/mintlify/cn/cli/overview.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: "CLI 概览" -description: "所有 forge 命令按 Core、Memory、Substrate、Quality、Config 五组罗列，并附上控制强制策略、命令输出与秘密再编辑的环境变量，包括 FORGE_ENFORCE、FORGE_GUARD_STRICT 与 FORGE_VERBOSE 的说明。" ---- - -`forge` 命令表以数据形式定义在 `src/commands.js` 里，并由 `forge docs check` -对着文档核对，所以一个命令没法在文档没注意到的情况下就上线或消失。命令按五组 -组织。 - - - - 引导和维护：`init`、`sync`、`doctor`、`catalog`、`docs`、`update`。 - - - 跨会话与团队记忆：`cortex`、`recall`、`remember`、`brain`、`ledger`、 - `reuse`、`handoff`、`decide`。 - - - 动作前门及其各个阶段：`substrate`、`preflight`、`route`、`impact`、 - `scope`、`context`、`anchor`、`diagnose`、`imagine`、`lean`。 - - - 验证与安全：`verify`、`scan`、`spec`、`taste`、`uicheck`、`harden`。 - - - 提供方、成本、仪表盘、品牌、atlas、技术栈：`config`、`cost`、`dash`、`brand`、 - `atlas`、`stack`。 - - - -## 约定 - -- **默认建议性。** 设置 `FORGE_ENFORCE=1` 就能让基底在最强信号上变成硬阻塞 - （空洞的提示、无法拼齐的必需上下文、超出默认 25 文件阈值的爆炸 - 半径）。 -- **默认安静。** 每条命令的 `Forge — …` 标题只是品牌装饰，藏在 - `--verbose` / `FORGE_VERBOSE` 后面；命令会先输出它的结果。 -- **管道友好。** 被管道时输出纯文本；在 TTY 上会加上品牌配色和 - 置信度条。`NO_COLOR` 关闭颜色，`FORCE_COLOR=1` 强制打开。 -- **`--json`** 在基底和大多数分析类命令上都可用，方便脚本化。 - -## 环境变量 - -| 变量 | 作用 | -| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `FORGE_ENFORCE=1` | 把基底最强的建议性信号变成硬阻塞。 | -| `FORGE_GUARD_STRICT=1` | 把秘密脱敏器的 `DEGRADED` 警告升级为阻塞式退出。默认情况下，一次脱敏失败会把 `secret redaction DEGRADED` 打到 stderr 并放行输出；严格模式则拒绝输出任何脱敏器没能完全清洗干净的内容。适合在 CI 或共享机器上使用 —— 那里一行未脱敏内容比一次失败的命令更糟。 | -| `FORGE_NO_UPDATE_CHECK=1` | 让 `forge doctor` 里的"落后上游若干次提交"提示安静下来。 | -| `FORGE_NO_HINT=1` | 静音那条一次性、提示你去跑 `forge init` 的初始化提示。 | -| `FORGE_VERBOSE=1` | 显示每条命令默认隐藏的横幅（`Forge — …`）。 | -| `FORGE_EMBED=1` | 为记忆召回选择接入 embedding 层（MinHash 仍是零依赖的默认方案）。 | -| `FORGE_LEDGER_ONLY=0` | 应急开关。仅 ledger 现为默认——记忆只存放在 `.forge/ledger` 中，旧的 `lessons/*.md` 与 fact 文件不再写入。设为 `0` 可恢复旧的文件存储。 | - - - 运行 `forge --help` 得到永远最新的命令列表，或 `forge catalog` 得到 - 一份"Start Here"索引，列出每个工具、crew 和护栏，附上一行简介。 - - -## 更新的命令与标志 - -这些命令和标志均已可用。它们在各自的分组页里都有 -文档，并会在行内标注： - -| 命令 / 标志 | 分组 | 作用 | -| ---------------------- | -------- | ------------------------------------------------ | -| `forge know` | Memory | 把一条事实路由到它正确的存储归宿。 | -| `forge deja` | Memory | 相似历史工作查找。 | -| `forge precommit` | Quality | 提交级验证门。 | -| `forge radar` | Quality | 依赖新鲜度环。 | -| `forge report` | Config | 仓库 Forge 状态的静态 HTML 报告。 | -| `forge tools` | Config | 主工具选择 + gitignore 接线。 | -| `forge verify --deep` | Quality | 多视角共识验证。 | -| `forge update --to` | Core | 固定或降级到某个具体版本。 | diff --git a/mintlify/cn/cli/quality.mdx b/mintlify/cn/cli/quality.mdx deleted file mode 100644 index c2b08e7..0000000 --- a/mintlify/cn/cli/quality.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "Quality 命令" -description: "验证与安全：verify、scan、spec、taste、uicheck 和 harden。" ---- - -Quality 分组是验证和安全面。它们如何组合，见 -[验证门](/cn/concepts/verification-gates)。 - -## `forge verify` - -独立验证门 —— 测试 + 幻觉符号 + 出处溯源。 - -```bash -forge verify -forge verify --deep # multi-lens consensus -``` - -`forge verify --deep` 汇报的是一个四态的 `status`，而不是简单的 pass/fail： - -| 状态 | 含义 | -| ---------------- | ------------------------------------------------------------------------------------- | -| `PASS` | 每一个视角都一致通过，**并且**核心 `forge verify` 的测试状态也是 `PASS`。 | -| `FAIL` | 至少有一个视角报出了真实的失败。 | -| `INCOMPLETE` | 某个视角没能跑完（超时、崩溃、依赖缺失）—— 视为未被证明。 | -| `NOT_CONFIGURED` | 这个仓库没有接通任何视角 —— 实际上什么都没检查。 | - -只有 `PASS` 才算已验证。`--deep` 有意拒绝在底层 `forge verify` 的测试状态不是 `PASS` -时把共识提升为 `PASS`，所以一次绿色的 deep 运行永远意味着一次绿色的 -base 运行。 - -## `forge scan` - -技能门 —— 在安装前审核一个 skill 或 MCP 服务器是否有注入 / RCE / 数据外泄风险。 - -```bash -forge scan -``` - -## `forge spec` - -规范即契约 —— 初始化（OpenSpec）、锁定，并检查漂移。 - -```bash -forge spec init -forge spec lock -forge spec check -``` - -## `forge taste` - -为本仓库启用一个 UI-taste 工具（不带参数会列出可选项）。 - -```bash -forge taste # list the profiles -forge taste # brutalist · corporate · editorial · minimalist · playful -``` - -会写出 `DESIGN.md` 并对 `uicheck design` 门的阈值做参数化。 - -## `forge uicheck` - -确定性的 UI 检查。 - -```bash -forge uicheck contrast # WCAG contrast ratio -forge uicheck fingerprint # deterministic design fingerprint -forge uicheck design # slop-distance + conformance gate -forge uicheck visual # Playwright-rendered check (opt-in tier) -``` - -## `forge harden` - -接通安全控制 —— gitleaks pre-commit + 沙盒设置。 - -```bash -forge harden -``` - -## `forge precommit` - -提交级门 —— 在提交时跑一遍验证底线，让部分完成或未验证的 -工作在落地之前就被拦住。 - -```bash -forge precommit -``` - -## `forge radar` - -依赖新鲜度环 —— 按项目依赖的新鲜程度分组，让陈旧或漂移中的依赖 -在咬人之前先浮出水面。 - -```bash -forge radar -``` - -如何读这些环，见 [保持依赖新鲜](/cn/guides/radar-deps) 指南。 diff --git a/mintlify/cn/cli/substrate.mdx b/mintlify/cn/cli/substrate.mdx deleted file mode 100644 index 78cb06c..0000000 --- a/mintlify/cn/cli/substrate.mdx +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: "Substrate 命令" -description: "动作前门以及可以单独调用的各个阶段：substrate、preflight、route、impact、scope、context、anchor、diagnose、imagine 和 lean。" ---- - -Substrate 分组就是动作前门。`forge substrate` 把其他阶段组合成一个统一的 -裁决；每个阶段也可以单独调用。管线细节见 -[动作前门](/cn/concepts/pre-action-gate)。 - -## `forge substrate` - -一个动作前门：assumptions、route、impact、scope、memory、verify。 - -```bash -forge substrate "" -forge substrate "" --json -``` - -如果它返回 `okToProceed:false`，在编辑前先问它返回的 `assumption.questions`。 - -## `forge preflight` - -假设检查 —— 找出任务里点名了但仓库并未定义的东西。 - -```bash -forge preflight "" -``` - -## `forge route` - -为一个任务推荐最便宜的能胜任的模型。 - -```bash -forge route "" -forge route gateway # emit LiteLLM gateway config -``` - -## `forge impact` - -从 atlas 图中预测某个符号或文件的爆炸半径。 - -```bash -forge impact -``` - -## `forge scope` - -把文件拆解成独立的簇 —— 外加你没点名的耦合文件。 - -```bash -forge scope -``` - -## `forge context` - -有预算的上下文拼装 + 完备性门 —— 一次编辑必须知道的东西。 - -```bash -forge context "" -``` - -在预测的编辑集合上用集合覆盖法拼装出一个受预算约束的上下文，套一层 -压缩阶梯，并报告算出来的缺失集合。 - -## `forge anchor` - -目标漂移检查 —— 你实际的（git）改动是不是还在既定目标上？ - -```bash -forge anchor set "" # persist the goal across sessions -forge anchor show -forge anchor clear -``` - -## `forge diagnose` - -死循环检查 —— 记录一次失败；同样特征连续出现 3 次会生出一条诊断 + 上报。 - -```bash -forge diagnose "" -``` - -## `forge imagine` - -后果模拟 —— 针对某个任务给出预测的破坏点 + 最小的干跑测试套件。 - -```bash -forge imagine "" -forge imagine "" --run # execute the minimal suite sandboxed -``` - -## `forge lean` - -范围最小性 (M5) —— 衡量 diff 的足迹相对任务所要求的大小。 - -```bash -forge lean -``` - - - `route`、`impact`、`scope`、`context`、`anchor` 和 `lean` 各阶段都在 - `forge substrate` 里跑。当你只需要某一个信号时才单独调用它们。 - diff --git a/mintlify/cn/concepts/config-compiler.mdx b/mintlify/cn/concepts/config-compiler.mdx deleted file mode 100644 index 9f49274..0000000 --- a/mintlify/cn/concepts/config-compiler.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: "四层配置编译器" -description: "只写一次基底；forge sync 会把它编译成每个工具的原生配置。四层描述的是这个大脑如何被表达，编译器描述的是它如何被交付。" ---- - -你只写一次基底。`forge sync` 会把这份来源编译成每个工具的原生 -配置。四层描述的是 _大脑如何被表达_；编译器描述的是它 _如何被 -交付_。 - -```mermaid -flowchart TD - S["source/ · rules.json · substrate.json · mcp.json"] -->|"forge sync — content-hash + DO-NOT-EDIT headers"| N["native configs · CLAUDE.md · AGENTS.md · .cursor · .gemini · .aider"] - S -. configures .-> L - subgraph L["the four layers"] - direction LR - T["tools · model-invoked skills"] - C["crew · isolated sub-agents"] - G["guards · deterministic hooks"] - M["mcp · atlas + substrate server"] - end -``` - -## 一份来源，多个输出 - -规则只写**一次**（`source/rules.json`）；一个确定性的编译器（`forge sync`） -把它输出成每个工具的原生格式，带一个内容哈希头，所以漂移是可探测的， -再跑一次是幂等的。任何一条规则都不会被写两遍。规范来源由三个 -文件组成： - -| 来源文件 | 存放什么 | -| ----------------------- | -------------------------------------------------------------------- | -| `source/rules.json` | 规范的工程规则（git、测试、安全、风格）。 | -| `source/substrate.json` | 认知基底默认值 —— 阈值、路由、LLM 的调节参数。 | -| `source/mcp.json` | 输出到每个工具的 MCP 服务器定义。 | - -## 四层 - -每一层都有品牌名，并且跨工具输出。 - - - - `~/.forge/tools/` → `~/.claude/skills/`。模型可调用的 skill，遵循 - `SKILL.md` 标准（frontmatter 里的 `name` + `description`）。 - - - `~/.forge/crew/` → `~/.claude/agents/`。上下文隔离的子代理，例如 scout、 - verifier 和 frontend-verifier。 - - - `~/.forge/guards/` → `settings.json` hooks。**唯一进行 _强制_ 而不只是 - _建议_ 的层。** 一个 guard 就是一个确定性钩子，模型没法漂离它。 - `CLAUDE.md` 里的自然语言规则会被口头承认，然后在压缩之后被遗忘；一个 guard - 不会。每一条可强制的不变量都应该落在这里。 - - - Forge 内置一个 stdio 服务器（`src/cortex_mcp.js`），暴露 19 个 MCP 工具： - 基底检查（`substrate_check` / `predict_impact` / `assumption_gate` / …）、 - 记忆的读 _和_ 写（`forge_remember`、账本的 ratify/retract），以及运维/健康检查。 - - - -有几个横切关注点贯穿四层：**atlas**（代码图）、**lean** -（最小性 —— 既作为一个 tool 又作为一个 Stop-guard 交付，所以不管 -模型是否主动调用它都会生效），以及 **recall**（记忆）。 - -## Guard 胜过自然语言 - -模型允许漂离的规则活在自然语言里；模型**永远不能**打破的规则 -活在 guards 里（确定性 shell 钩子）。一个 guard 在上下文 -压缩之后也不会被遗忘。 - - - 把每一条可强制的不变量从 `CLAUDE.md` 里挪进一个 guard；让自然语言 - 尽量薄。这是 Forge 设计里最重要的一条纪律。 - - -## 已验证的跨工具输出矩阵 - -Forge 为**九个工具**输出配置，加上一个给 Roo Code 和 VS Code 的 MCP 服务器。每 -一行都对着厂商文档核对过。 - -| 工具 | 原生目标 | Forge 如何输出 | -| ------------------ | ---------------------------------------------------------------- | ---------------------------------------------------------------------- | -| **Claude Code** | `CLAUDE.md`（+ `.claude/rules/*.md`、`settings.json`） | 一份很薄的 `CLAUDE.md`，第一行是 `@AGENTS.md`；guards → settings | -| **Codex** | 原生的 `AGENTS.md`（32 KiB 上限） | 根目录下的规范 `AGENTS.md` **就是**那份来源 | -| **Cursor** | `AGENTS.md` + `.cursor/rules/*.mdc` | 扁平规则用 `AGENTS.md`；需要限定作用域时用 `.mdc` | -| **Gemini** | `GEMINI.md`，或通过 `context.fileName` 选择 `AGENTS.md` | 写一份 `.gemini/settings.json`，避免出现第二份副本 | -| **Aider** | 通过 `.aider.conf.yml` 里的 `read:` 引用 `CONVENTIONS.md` | 输出一份 `.aider.conf.yml`，里面 `read: AGENTS.md` | -| **Copilot** | 根目录 `AGENTS.md` + `.github/copilot-instructions.md` | 依赖根目录的 `AGENTS.md`；可选加一个 `.github` 指针 | -| **Windsurf/Devin** | 自动发现的 `AGENTS.md`（上限 6k/12k 字符） | 根目录 `AGENTS.md` 保持在上限之内；识别 `.windsurf` 或 `.devin` | -| **Zed** | 一个优先级列表里的第一个匹配，包括 `AGENTS.md` | 输出 `AGENTS.md`；doctor 会标出任何遮蔽它的老式文件 | -| **Continue** | `.continue/rules/*.md` + `.continue/mcpServers/*.yaml` | 输出一份 rules 文件，外加 Forge 的 MCP 服务器配置 | - -Roo Code 和 VS Code 通过 `forge init`（`.roo/mcp.json`、 -`.vscode/mcp.json`）拿到 Forge 的 MCP 服务器，而不是一份规则文件。 - - - **字符上限是真的存在。** Codex 在 32 KiB 处截断，Windsurf 在 6k/12k 处截断。 - `forge sync` 会强制一个源大小预算，避免配置被悄悄截断。 - diff --git a/mintlify/cn/concepts/cross-session-memory.mdx b/mintlify/cn/concepts/cross-session-memory.mdx deleted file mode 100644 index de99063..0000000 --- a/mintlify/cn/concepts/cross-session-memory.mdx +++ /dev/null @@ -1,90 +0,0 @@ ---- -title: "跨会话记忆" -description: "会话锚定、完成门、handoff 快照和决策日志 —— 用来终结会话失忆和半成品工作的一层。" ---- - -这一层存在的意义是要消灭两种失败模式：**半成品工作**（代码改了，但依赖 -它的产物没跟着改）和**会话失忆**（下一个会话把这一个知道的东西又假设了 -一遍）。指令只是提升正确行为的 _概率_；确定性的钩子才能保证一个 _底线_。 - -## 会话锚定 - -在 `SessionStart` 上（`src/session.js`），Forge 每次会话记录一次 `HEAD`，清理 -一周前的会话产物，并注入一份新鲜的定位信息： - - - - 从过去的修正中挖掘出来的 Cortex 经验。 - - - 既定的目标，好让漂移可以对着它衡量。 - - - 上一个会话写下的、有界的 `.forge/state.md`。 - - - 最近的提交和未提交的变更 —— 证据，而不是先验假设。 - - - -新会话是基于证据定位的，而不是基于先验。 - -## 完成门 - -Stop 路径上唯一有资格作出回应的 guard 是 `completion-gate.sh` -（`src/gate.js`）。它同步运行；负责挖掘经验的 `cortex.sh stop` 保持后台运行 -并永远不能阻塞。 - -变更集合是**会话范围**的：来自 committer 时间不早于会话开始时间的提交里的 -文件，加上工作区的变更，减去 `SessionStart` 时快照的脏东西 —— -所以已存在的编辑、切分支、`git pull` 都不会被算到代理头上。 - - - 如果代码动了，但没有对应的文档或状态产物跟进，这个门会**阻塞一次**， - 并以一份修复清单作为原因。其他所有情况都放行，任何内部错误 - 也都放行（fail-open）。`FORGE_STOPGATE=0` 可以关掉它。 - - -对于动了代码的会话，这个门还要求提供**测试证据** —— 要么会话 diff 里有一个 -测试文件，要么针对当前变更有一次新鲜通过的 `forge verify`。仅凭一份 -`forge handoff` 快照，已经不足以清掉这个门的代码变更这一支。 - -修复清单指向那些能收尾工作的工具： - -```bash -forge verify # record the test evidence for code changes -forge docs sync # sweep the diff for stale doc mentions -forge handoff "" --next "" # write the bounded session snapshot -forge decide " — " # record a choice so no session re-decides it -``` - -## Handoff 和 decisions - -两个存储把知识跨会话保留下来： - -| 存储 | 语义 | -| --------------------- | ------------------------------------------------------------------------------------ | -| `.forge/state.md` | 有界的**重写**（快照）—— 加载成本永远是 `O(bound)`。 | -| `.forge/decisions.md` | 只追加的 **ADR-lite**（`D-####`），带一份机器可读的决策账本副本。 | - -两者在写入时都拒收秘密。`state.md` 每次会话开始时会重新注入； -`decisions.md` 在重新决定过去某个会话已经定下的事情之前会被读一遍。 - -```bash -forge handoff "" --next "" -forge decide " — " -forge decide # read the log before re-deciding -``` - -## 由 diff 驱动的文档扫描 - -`forge docs sync` 回答一个 diff 形状的问题：变化过的标识符（路径、 -定义和被调用的符号，来自新增 _和_ 删除的行）对着每份文档 -产物扫描 → UPDATED / STALE（带 file:line 命中）/ VERIFIED-UNAFFECTED，并把 -原因记录下来。它只做汇报；牙齿由完成门提供。 - - - `recall` 和 `cortex` 只是文件加提示词的记忆 —— **不是**权重级别的学习。 - Consolidate 是一个可能产生幻觉的摘要器，所以它保持建议性、 - 可由人审阅、且不含秘密。 - diff --git a/mintlify/cn/concepts/model-routing.mdx b/mintlify/cn/concepts/model-routing.mdx deleted file mode 100644 index 635d69b..0000000 --- a/mintlify/cn/concepts/model-routing.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "模型路由" -description: "在分发前，通过一份确定性、可 diff 的评分表挑出最便宜的能胜任的模型层 —— 并且对自建网关有一个安全回退的重映射。" ---- - -在分发**之前**，Forge 会根据一份你可以在仓库里读到的确定性评分表 -（`src/model_tiers.json`）为一个任务推荐最便宜的能胜任的模型。和那种 -在请求时由代理内部决定的网关不同，路由决策在 git 里是可见、可 diff 的。 - -## 推荐一个层 —— `forge route` - -```bash -forge route "" # cheapest capable model tier for the task -forge route gateway # emit LiteLLM gateway config -``` - -推荐依据是在一份带标签的样本库（英文 + Hinglish 行）上、 -在重叠相似度度量下、带一个置信度门槛的样本 k-NN 数学 —— 而不是关键词匹配。 - - - 从推荐的 `route.tier` 开始，只在某个外部验证器失败之后再升级， - 绝不预防性地升级。这样能在任务确实需要能力时不封顶能力， - 同时把开销压下去。 - - -## 先意图，再层级 - -路由和意图检测共享同一套数学（`src/intent.js`）：一段提示通过同一个样本 -k-NN 估计器被映射到某个意图。注意两者用的停用词集合不同 —— route -把通用动词（`fix` / `add` / `build`）视为复杂度噪音，但那些动词 -恰恰是意图的信号。 - -## 层级表 - -层级表（`src/model_tiers.json`）按家族（haiku / sonnet / opus / fable） -钉死了公开的 Anthropic 模型 ID。文档里的价格由文档检查 -对着这份文件核对，所以自然语言和表不会漂移。 - -## 自建网关的重映射 - -一个自建的 LiteLLM 或代理网关会用它自己的模型名，所以原封发送一个 -出厂 ID 会 404。当配置了非默认网关的 base URL 时，Forge -（`src/gateway_model_map.js`）会**每个进程一次**地 `GET /v1/models`，并把它 -公示的每个 id 对每一层的家族打分： - - - - 家族关键词（haiku / sonnet / opus / fable）必须匹配 —— 这是硬门槛。 - - - 在同一家族里，用该层名字 token 的 `setOverlap` 系数挑出 - 最佳匹配。 - - - 平局时倒向最接近规范名的 id。 - - - - - 只有当解析出来的 id 是 _出厂_ ID 时，重映射才会向网关请求 —— 一个显式的 - `.forge/providers.json` 别名或 `ANTHROPIC_MODEL` 覆盖永远不会 - 被动。它会在没有网关、无法访问 `/v1/models`，或没有匹配到家族时 - 安全地退回到出厂 ID，所以直连 `api.anthropic.com` 的用户是逐字节相同的。 - - -`forge doctor` 的 **gateway models** 一行会打印出解析后的 `tier → model` -映射，方便核对。 - -## 提供方与成本 - -```bash -forge config # show / switch / add providers, set the default model -forge cost # real per-day spend -forge cost --stages # measured per-stage cost factors -``` - - - `forge cost --stages` 只报告**实测的阶段** —— 一个没有事件记录的阶段会显示 - "no data"，绝不会给出默认值。数字在被实测之前只是一个假设。 - diff --git a/mintlify/cn/concepts/pre-action-gate.mdx b/mintlify/cn/concepts/pre-action-gate.mdx deleted file mode 100644 index 44af24a..0000000 --- a/mintlify/cn/concepts/pre-action-gate.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: "动作前门" -description: "forge substrate 在模型编辑代码之前跑一次有序的检查，并返回一个统一裁决 —— 假设、路由、影响、范围、记忆和验证。" ---- - -**认知基底** —— 在模型编辑代码之 _前_ 运行的一层。`forge substrate -""`（以及 MCP 工具 `substrate_check`）跑一次有序的检查，并返回一个统一 -裁决。它把可单独调用的阶段 —— `preflight`、`route`、`atlas`、`impact`、 -`reuse`、`context`、`scope`、`lean`、`anchor`、`verify` —— 组合成一份动作前 -契约。 - -```mermaid -flowchart TD - RE["referenced entities"] --> INTAKE - subgraph INTAKE["intake"] - direction LR - PF["preflight · assumption gap"] --> RT["route · cheapest tier"] - end - INTAKE --> ANALYSIS - subgraph ANALYSIS["analysis"] - direction LR - AT["atlas · code graph"] --> IM["impact · blast radius"] --> PT["predict · failing tests"] --> RU["reuse · cache hit?"] - end - ANALYSIS --> SAFETY - subgraph SAFETY["safety + fit"] - direction LR - CX["context · completeness gate"] --> SC["scope · coupled files"] --> ME["memory · recall + lessons"] --> MN["minimality · lean footprint"] --> GA["goal-anchor · drift check"] - end - SAFETY --> VD["verdict"] -``` - -## 三个阶段 - - - - **preflight** 找出假设缺口 —— 任务里点名了但仓库并未 - 定义的东西。**route** 挑出最便宜的能胜任的模型层。 - - - **atlas** 读取代码图，**impact** 计算爆炸半径，**predict** - 点名可能失败的测试，**reuse** 检查是否有已验证的缓存命中。 - - - **context** 跑完备性门，**scope** 揭示耦合文件，**memory** - 注入 recall + 经验，**minimality** 衡量 lean 足迹， - **goal-anchor** 检查漂移。 - - - -## 爆炸半径 - -**爆炸半径** —— 从代码图中读出的、一次编辑预测会影响的文件集合。 -`forge impact` 计算它；管线在模型触碰任何东西之前把它显示 -出来。 - -```bash -forge impact verifyToken # predicted impacted files for a symbol -forge impact src/auth.js # …or for a file -``` - -## 默认建议性 - -裁决**默认是建议性的** —— 它报告，不阻塞。设置 -`FORGE_ENFORCE=1` 就能把最强的信号变成硬阻塞： - - - - preflight 找不到可执行的意图 —— 任务表述不足。 - - - 完备性门盖不住预测的编辑集合。 - - - 受影响集合超过默认约 25 文件的阈值。 - - - -其他一切都保持为人可以覆盖的警告。 - - - 在 Claude Code 上，整个门会通过 `UserPromptSubmit` 钩子在**每次提示上 - 自动**运行 —— 对干净的任务保持静默。`forge substrate "" --json` - 给出可用于脚本的机器可读裁决。 - - -## 运行它 - -```bash -forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" -forge substrate "" --json -``` - -如果裁决是 `ASK FIRST`，在编辑前先问它返回的 `assumption.questions` —— -不要对一个表述不足的任务瞎猜。从推荐的 `route.tier` 开始，只在某个 -外部验证器失败之后再升级，绝不预防性地升级。 - - - 记忆阶段从那本携带证据的账本里读取。 - diff --git a/mintlify/cn/concepts/proof-carrying-memory.mdx b/mintlify/cn/concepts/proof-carrying-memory.mdx deleted file mode 100644 index bd20923..0000000 --- a/mintlify/cn/concepts/proof-carrying-memory.mdx +++ /dev/null @@ -1,113 +0,0 @@ ---- -title: "携带证据的记忆" -description: "每一条被存下来的事实、经验或复用产物都是一个自带证据的声明 —— 只有当独立裁决者把它的置信度抬升到底线之上时才被信任。" ---- - -**Proof-carrying memory (PCM)** —— 每一条被存下来的事实、经验或复用产物都是一个 -_声明_，自带它的证据。只有当独立裁决者（测试、CI、人的 -接受/回退）把它的置信度抬升到底线之上时它才被信任。一条错误的经验会 -衰减掉，而不是被固化下来。 - - - "携带证据的记忆"是我们给**以证据为依据、按内容寻址的 - 记忆**起的名字 —— 一个由自身内容哈希寻址、并且链接到其 - 背后裁决者结果的声明。"proof"（证据）指的是这条证据链加上置信度规则， - **不是形式化机器可校验的证明**；回路里没有定理证明器。 - - -## 一份存储，多个写入者 - -所有记忆子系统都汇聚到同一份存储。`recall`、`remember`/`brain`、`cortex` -经验、`reuse` 产物和死循环 `diagnose` 结果都会把按内容寻址的 -声明写进 `.forge/ledger/`。 - -```mermaid -flowchart LR - subgraph EV["local events"] - direction TB - E1["recall / remember"] - E2["cortex lesson"] - E3["reuse mint"] - E4["diagnose"] - end - EV -->|"content-addressed claims"| LG["(.forge/ledger)"] - O["independent oracles · tests · CI · human accept/revert"] -->|"append evidence · move confidence"| LG - TM["teammate ledgers"] <-->|"git union-merge · conflict-free"| LG - LG --> RV["merged read view · recall list · lesson inject · brain index"] -``` - -## 为什么它无冲突地收敛 - -因为一个声明的字节内容是 `(kind, body, scope)` 的纯函数，每个副本都 -算出同一个身份 —— 所以队友的账本可以走普通 git 无冲突地合到一起。 - -机制上： - -- **证据和 tombstone 是只追加的**、哈希去重的日志。 -- **置信度（`val`）** 是一个带衰减的 Beta 后验，只有裁决者才能移动。 -- **合并是一个 join-semilattice** —— 已用性质测试证明是可交换、可结合、 - 幂等的 —— 所以账本无论以什么顺序都会收敛。 - - - `forge init` 会输出账本所需的 union-merge `.gitattributes` 规则；`forge - ledger merge ` 可以把任何另一个账本树合进来。完整决策记录在 - ADR-0006 (proof-carrying memory) 里。 - - -## 只有裁决者才能移动置信度 —— 别的都不行 - -只有独立的裁决者才能移动一条记忆的置信度： - - - - 一个通过的、能行使这条声明的测试，会抬高它的置信度。 - - - 一条绿灯的流水线是这条声明依然成立的独立证据。 - - - 人显式接受或直接回退是最强的信号。 - - - -无法验证的证据会被 `ORACLES` 表（`src/ledger.js`）里的封闭清单拒绝。 -未经审阅的知识会向 _不确定_ 衰减，而不是被删除 —— 沉睡的声明会 -保留下来用于审计，绝不会被悄悄移除。 - -## 账本表面 - -```bash -forge ledger stats # what the repo knows, by kind and trust level -forge ledger verify # re-check claims are in normal form -forge ledger show # a claim and its evidence trail -forge ledger blame # who minted it, every oracle outcome, per-author trust -forge ledger query "" # retrieve claims by relevance -forge ledger ratify # human accept -forge ledger retract # tombstone a claim -forge ledger merge # fold a teammate's ledger in, conflict-free -forge ledger import # bridge legacy stores into the ledger -``` - -加 `--personal` 是每用户的账本。 - -## reuse 缓存也是携带证据的 - -`forge reuse` 是一份携带证据的代码缓存。一件生成的产物只有当它的 -证据还成立时才会被再次交付出来 —— 置信度在底线之上，**且** -它的 atlas 依赖仍然可以解析。否则就会 fall through 到生成，并在 -返回的路上再生成一条新的声明。 - -```mermaid -flowchart LR - SP["spec"] --> FP["fingerprint · MinHash + LSH"] - FP --> LD["match ladder · exact to near to adapt to miss"] - LD --> GT{"confidence >= floor AND deps resolve?"} - GT -->|"yes"| SV["serve · proof holds"] - GT -->|"miss"| GN["generate"] - GN -->|"mint claim"| MT["(.forge/ledger)"] -``` - - - MinHash 的近似匹配在非常短的 spec 上比较弱。一个可选的 embeddings 后端 - （`FORGE_EMBED`）可以缓解这一点；MinHash 依然是零依赖的默认方案。 - diff --git a/mintlify/cn/concepts/verification-gates.mdx b/mintlify/cn/concepts/verification-gates.mdx deleted file mode 100644 index a6bec3c..0000000 --- a/mintlify/cn/concepts/verification-gates.mdx +++ /dev/null @@ -1,132 +0,0 @@ ---- -title: "验证门" -description: "独立验证、幻觉符号标记、规范即契约以及技能门 —— 一些能减轻但从不认证正确性的检查。" ---- - -不跑一次可以复核的检查 —— 一个测试、一个构建退出码、一张截图 —— -就没有"完成"。Forge 的每一个验证门都多接住一次。设每个任务的漏检率 -为 `1 − p`，某个门的接住率为 `c`，那么被漏掉的错误会降到 `(1 − p)(1 − c)`， -这里每一个门都是多一个 `c`。 - - - **验证是减轻，不是认证。** Crew 验证者和幻觉符号 - 标记能减少评审负担；它们并不证明代码是正确的。测试和人的 - 修正永远拥有最终发言权。 - - -## 独立验证 —— `forge verify` - -一个独立的门：它跑仓库真正的测试、标出幻觉符号，并 -检查出处溯源。 - -```bash -forge verify # tests + hallucinated-symbol + provenance -forge verify --deep # multi-lens consensus — several independent checks must agree -``` - - - `--deep`升级为一个多视角共识：变更必须过几个 - 独立的验证视角，而不只是一个。 - - -`forge verify --deep` 汇报的是一个四态的 `status`，不是二元的 pass/fail： - -- `PASS` —— 每一个视角都一致通过，**并且**核心 `forge verify` 的测试状态也是 - `PASS`。只有这个状态才算已验证。 -- `FAIL` —— 至少有一个视角报出了真实的失败。 -- `INCOMPLETE` —— 某个视角没能跑完（超时、崩溃、依赖缺失）。什么都没被证伪， - 但也什么都没被证明。 -- `NOT_CONFIGURED` —— 这个仓库没有接通任何视角，所以 `--deep` 无东西可查。 - -`PASS` 蕴含 base 也是 `PASS` 这条规则是有意为之：一次绿色的 deep 共识永远 -不能跑赢一次红色的 base 运行，所以 base 测试视角上的 `INCOMPLETE` 或 -`NOT_CONFIGURED` 会把 deep 的结果同步降级。 - -## 幻觉符号标记 —— `forge atlas has` - -`forge atlas has ` 是幻觉检查：如果模型调用了一个不在代码图里的 -符号，这个门会标出来。 - -```bash -forge atlas build # index this repo's symbols → .forge/atlas.json -forge atlas has useAuth # "not found" = likely hallucinated -``` - -atlas 有意做成纯 JSON —— Codex、Cursor、Gemini 和 Aider 都能通过 CLI 或 -简单的 `jq` 来读 `.forge/atlas.json`，消费端不需要依赖 MCP。 - -## 规范即契约 —— `forge spec` - -把行为钉在一份规范上，并检测相对它的漂移： - -```bash -forge spec init # scaffold an OpenSpec contract -forge spec lock # lock the current spec as the contract -forge spec check # report drift against the locked contract -``` - -## 技能门 —— `forge scan` - -在安装一个 skill 或 MCP 服务器之前，审核它是否有注入、RCE 或数据外泄的风险： - -```bash -forge scan -``` - - - 一次干净的扫描**不等于安全认证。** 内置启发式只能捕捉 - 已知的攻击形状（critical）和少数几种高严重度模式；通过意味着 _"没有检测到 - critical 特征"_，而不是 _"可以放心安装"_。始终自己审阅源码、 - 权限、包的来源和网络行为。一次 **high** 严重度的发现即便没有硬阻塞， - 也不会被标记为安全。外部扫描器是按需启用的，除非你打开，否则不会 - 发起任何网络调用。 - - -## 加固 —— `forge harden` - -接通把秘密和不安全变更挡在外面的安全控制： - -```bash -forge harden # gitleaks pre-commit + sandbox settings -``` - -## 提交级门 —— `forge precommit` - - - `forge precommit`是一个提交级门 —— 它在提交时跑一遍验证底线， - 让部分完成或未验证的工作在落地之前就被拦住。 - - -## 完成门 —— 必须有测试证据 - -Stop 路径上的完成门（见 -[跨会话记忆](/cn/concepts/cross-session-memory)）不再接受一份代理 handoff 作为 -代码变更已完成的证明。对任何动了源码的会话，这个门都要求**真实的测试证据**： - -- 会话 diff 里改动过一个测试文件，**或者** -- 针对当前变更有一次新鲜通过的 `forge verify` 记录在案。 - -单独一份 `forge handoff` 快照并不能满足这个门 —— 它记录的是意图，而不是 -验证。如果两种证据都没有，这个门会**阻塞一次**，并附上一份修复清单： - -```bash -forge verify # produce the test evidence -forge handoff "" --next "" # then snapshot the session -``` - -只改文档、只改配置以及其他非代码的会话不受影响 —— 只有当会话的 diff 真的 -动了代码时，测试证据的要求才会触发。 - -## UI 检查 —— `forge uicheck` - -确定性的 UI 检查，前三个视角不需要 LLM 也不需要截图： - -```bash -forge uicheck contrast # WCAG contrast ratio -forge uicheck fingerprint # deterministic design fingerprint -forge uicheck design # slop-distance + conformance gate -forge uicheck visual # Playwright-rendered check (opt-in tier) -``` - -配合 `forge taste` 用来挑一个视觉方向（brutalist、corporate、 -editorial、minimalist、playful），并对 `design` 门的阈值做参数化。 diff --git a/mintlify/cn/guides/radar-deps.mdx b/mintlify/cn/guides/radar-deps.mdx deleted file mode 100644 index b7e2494..0000000 --- a/mintlify/cn/guides/radar-deps.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: "用 radar 保持依赖新鲜" -description: "forge radar 把你的依赖按新鲜程度分到多个环里，让陈旧或漂移中的依赖在咬人之前先浮出水面。" ---- - - - `forge radar` 已可用。这份指南描述它如何嵌入现有的 - 依赖新鲜度纪律；在你安装的版本里可用性以 `forge --help` 为准。 - - -Forge 的工程规则之一是：_在加一个依赖之前，从在线来源确认当下最佳 -的选项，并优先复用项目已经在用的东西。_ `forge radar` 把你依赖的 -当前状态可视化出来，好让这条规则有数据支撑。 - -## 想法：新鲜度环 - -`forge radar` 按每个依赖有多"新"把项目的依赖分到一圈圈**新鲜度环**里 —— -从中心的最新，到边缘的陈旧或漂移中。读这些环是一种快速回答 -"哪些东西我们让它漂了？"的方法，不用一个包一个包地手工审计。 - -```bash -forge radar -``` - -## 依赖列表从哪来 - -Radar 建立在同一套清单读取之上，它也是 `forge stack` 的动力，后者从 -仓库的依赖清单文件里探测它真实的技术栈： - -```bash -forge stack # languages, frameworks, package managers, real test commands -``` - -因为探测是数据驱动的，并且在各生态（`package.json`、 -`pyproject.toml`、`go.mod`、`Cargo.toml`、`Gemfile`、`composer.json`、`pom.xml` / -`build.gradle`、`*.csproj`）上是安全失败的，radar 可以对 `stack` 认得的 -同一批清单进行新鲜度推理。 - -## 在循环中使用它 - - - - 在添加或升级依赖之前，先跑一下 `forge radar`，看看哪些依赖 - 已经在漂了。 - - - 如果一个能胜任、又已经很新鲜的依赖已经在内圈里，那就复用它， - 而不是再加一个新的 —— 最能合身的最小变更胜出。 - - - 当你确实要升级或替换一个依赖时，把原因记录下来： - ```bash - forge decide "bump to — " - ``` - 这样将来的会话读到这份记录，而不是重新纠结一遍。 - - - - - Radar 报告新鲜度；它不会替你升级。把它的环当作一份供人做决定的 - 建议性输入 —— 任何一次升级在被称为完成之前，都要用仓库真正的 - 测试（`forge verify`）来验证一次。 - - - - 依赖升级之后，跑一遍 Quality 门 —— `forge verify` 和 `forge precommit`。 - diff --git a/mintlify/cn/guides/team-memory.mdx b/mintlify/cn/guides/team-memory.mdx deleted file mode 100644 index f9aff91..0000000 --- a/mintlify/cn/guides/team-memory.mdx +++ /dev/null @@ -1,79 +0,0 @@ ---- -title: "用账本实现团队记忆" -description: "把队友的账本无冲突地合进来，走的是普通的 git —— 没有服务器，没有同步服务，只是文件，无论以什么顺序都会收敛。" ---- - -基底学到的一切 —— cortex 经验、`forge remember` 事实、已验证的 reuse -产物 —— 都以按内容寻址的声明形式落到一份 git 原生的账本（`.forge/ledger/`）里， -它被设计成合并时不会有冲突。没有服务器，也没有同步服务；只是 git 里的 -文件。 - -## 团队记忆三条命令 - - - - ```bash - forge init - ``` - 这会输出账本所需的 `.gitattributes` union-merge 规则等内容。 - - - Cortex 经验和 `forge remember` 事实会在你干活时把声明影子写进账本 —— - 不用额外跑什么。 - - - ```bash - git pull && forge ledger merge - ``` - 任何顺序都行 —— 合并是无冲突的。 - - - -## 为什么它不会冲突 - -一个声明的字节内容是 `(kind, body, scope)` 的纯函数，所以每个副本对 -同一份知识都算出同一个身份。合并是一个 join-semilattice —— 已用 -性质测试证明是可交换、可结合、幂等的 —— 所以两个队友的 -账本无论谁先同步都会收敛到相同的状态。 - -```mermaid -flowchart LR - A["your ledger"] <-->|"git union-merge · conflict-free"| B["teammate ledger"] - A --> M["merged read view"] - B --> M - M --> R["recall list · lesson inject · brain index"] -``` - - - 同一份知识被独立地铸造两次，会收敛到**一个**声明， - 并在它的出处里保留每一位作者。 - - -## 信任与出处 - -置信度只能被独立裁决者移动 —— 测试、CI、人的接受/回退 —— 所以 -导入一份队友的账本并不会盲目相信他们的笔记；它导入的是他们的 -_证据_。 - -```bash -forge ledger blame # who minted a claim, every oracle outcome, per-author trust -forge ledger stats # the merged view, by kind and trust level -forge ledger verify # confirm every claim is in normal form -``` - -## 跨团队复用 - -一旦队友已验证的代码进入了合并后的账本，你就可以带着它的证据来复用它： - -```bash -forge reuse query "" -``` - -一次命中指向的是有效、经测试确认过的代码，以及能证明它的 -`forge ledger blame` —— 复用它，而不是重新生成。 - - - 沉睡的声明会保留下来用于审计，绝不删除；未经审阅的知识 - 会向 _不确定_ 衰减，而不是向删除衰减。账本是一条证据链， - 不是一个可以被悄悄丢失的缓存。 - diff --git a/mintlify/cn/guides/zero-config-onboarding.mdx b/mintlify/cn/guides/zero-config-onboarding.mdx deleted file mode 100644 index db52f1c..0000000 --- a/mintlify/cn/guides/zero-config-onboarding.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: "引导式、低配置的上手" -description: "五分钟就能上手：安装一次，一个仓库配置一次，做一个任务，然后看着账本从第二天开始回本 —— 是引导式、低配置，不是零操作。" ---- - -Forge 追求的是**引导式、低配置的上手** —— 一个新仓库通常能在大约五分钟内 -进入可干活状态。安装一次，一个仓库配置一次，做一个任务，然后账本从第二天开始 -回本。（是低配置，不是零配置：你仍然需要装 CLI，在每个仓库里跑 `forge init`， -一些路径会假设有 Bash、Git 和 `jq`。） - -```mermaid -flowchart TD - I["forge init"] --> Cfg["every tool configured from one source"] - Cfg --> Work["you work as usual"] - Work --> Gate["substrate checks each task · ask first? · which model? · what breaks?"] - Gate --> Edit["agent edits, with guardrails"] - Edit --> Learn["cortex learns from corrections"] - Learn -.->|next task is smarter| Work -``` - -## 1. 安装（一次） - -推荐的路径不需要 token 也不需要克隆： - - - -```bash Plugin -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit -``` - -```bash CLI -npm install -g @codewithjuber/forgekit -``` - - - -```bash -forge doctor # everything green? -``` - -## 2. 配置一个仓库（每个仓库一次） - -```bash -cd ~/your-project -forge init # emits AGENTS.md, CLAUDE.md, .gemini/settings.json, .aider.conf.yml … -``` - -现在 Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf、Zed 和 Continue -都从各自的原生文件里读**同一份**规则。以后要改规则，就编辑 -`source/rules.json`（或者放一份仓库级的 `.forge/rules.json`），然后跑 `forge sync`。 - -## 3. 使用认知基底 - -```bash -forge substrate "" # ask/route/impact/scope/reuse/context/memory/verify in one pass -forge substrate "" --json -forge impact # the blast radius on its own -``` - -如果 `forge substrate` 返回 `ASK FIRST`，在编辑前先问它返回的问题。 - -## 4. 使用附加功能 - -```bash -forge atlas build # index this repo's symbols → .forge/atlas.json -forge atlas query useAuth # where is it defined? -forge atlas has useAuth # does it exist? "not found" = likely hallucinated -forge recall add "db port" "Postgres is on 5433 here, not 5432" -forge catalog # the Start-Here index of everything -``` - -## 5. 第二天：账本正在学习 - -第一天基底学到的一切 —— cortex 经验、被记住的事实、已验证的 -代码 —— 都以声明的形式落到了 `.forge/ledger/`。 - -```bash -forge ledger stats # what the repo knows, by kind and trust level -forge ledger blame # who minted a claim, every oracle outcome -forge reuse query "" # verified code you already have -``` - - - 接下来：把队友的账本无冲突地合进来，走的是普通的 git。 - diff --git a/mintlify/cn/installation.mdx b/mintlify/cn/installation.mdx deleted file mode 100644 index 6fd915a..0000000 --- a/mintlify/cn/installation.mdx +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: "安装" -description: "通往同一棵树的三个入口：插件市场、npm 全局安装，以及一个不走注册表的 github: 安装方式 —— 还有贡献者用的软链接开发方案。" ---- - -Forge 采用**一棵树，三个入口**的设计：插件清单、加固过的安装脚本 -和 npm 的 bin 全都指向同一份 `global/` + `source/` 树。 -选一个适合你工具的通道。 - -## 选择一个通道 - - - - 面向 Claude Code 和 Codex。护栏自动接通；无需手动合并。 - - - 面向任何工具。从公共 npm 注册表获取 `forge` CLI。 - - - 不需要注册表 —— 直接从仓库安装。 - - - 克隆 + `npm link`，或者用 `bash install.sh` 走软链接方案。 - - - -## 环境要求 - -- **Node.js >= 20** -- **零运行时依赖** —— 一切都是 Node 内置。可选层 - （`FORGE_EMBED` 向量嵌入、`uicheck visual` 用的 Playwright）是按需开启，不会加进 - 必需依赖。 - -## 插件市场 - -对 Claude Code 和 Codex 推荐这条路径，不需要 token 也不需要克隆： - -```bash -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit -``` - -插件通过 `${CLAUDE_PROJECT_DIR}` 把护栏接通，所以动作前门和 -完成门在后台就会触发。 - -## npm 全局 - -面向任何工具，来自公共 npm： - -```bash -npm install -g @codewithjuber/forgekit -forge doctor # everything green? -``` - -## 不走注册表的 github: 安装 - -```bash -npm install -g github:CodeWithJuber/forgekit -``` - -## 贡献者 / 本地开发 - - - -```bash npm link -git clone https://github.com/CodeWithJuber/forgekit.git -cd forgekit -npm link -``` - -```bash install.sh (symlink setup) -git clone https://github.com/CodeWithJuber/forgekit.git -cd forgekit -bash install.sh -``` - - - -安装脚本经过加固：幂等、基于软链接、带备份，没有 `curl | sh`。 - -## 验证 - -不管你用了哪个通道，都可以确认安装状态： - -```bash -forge doctor # tools, guards, MCP auth, config drift, update status -``` - - - `forge doctor` 也会为 git 克隆版本给出一条不烦人的"落后上游多少提交"的提示。 - 设置 `FORGE_NO_UPDATE_CHECK=1` 可以让它安静下来。所有路径都是 fail-open —— - 离线或 detached HEAD 都会报告"unknown"，永远不会报错。 - - -## 保持 Forge 最新 - -```bash -forge update --check # report whether a newer version is available -forge update # apply the update (git checkout or npm/copy install) -forge update --to # pin or downgrade to a specific version -``` - - - 去快速开始，运行 `forge init` 和你的第一次基底检查。 - diff --git a/mintlify/cn/introduction.mdx b/mintlify/cn/introduction.mdx deleted file mode 100644 index 74d0ecf..0000000 --- a/mintlify/cn/introduction.mdx +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: "Forge：面向 AI 编码代理的认知基底" -description: "Forge 是每个无状态模型都缺失的认知基底 —— 记忆、预见和护栏 —— 以原生配置的形式交付到每一个 AI 编码代理。" ---- - -**为每个 AI 编码代理提供一个共同的大脑。** 大语言模型是无状态的：每次调用只有一个 -上下文窗口，之后就会被清空。它没有关于你团队所学的记忆，没有关于某次编辑会破坏什么的 -预见能力，也没有强制执行的护栏。Forge -(`@codewithjuber/forgekit`) 就是这层**认知基底** —— 在模型编辑代码之 -_前_ 运行的一层，提供以证据为依据、按内容寻址的记忆（我们 -称之为"proof-carrying memory"，携带证据的记忆）、启发式的影响预见，以及强制执行的护栏 —— -并且是一个**跨工具的配置编译器**，一次性把这个大脑作为原生配置交付到每个工具。 -Claude Code 是测试最深入的集成；其他工具也接收原生配置和 -MCP 工具，但真实场景下的锤炼较少。 - - - - 携带证据的记忆，可以在会话之间和团队成员之间持续存在。每一条经验、 - 事实和已验证的复用，都是一个自带证据的声明。 - - - 一次编辑的爆炸半径 —— 从代码图中读取到的、这次编辑预测会触及的文件集合， - 包括你从未点名的耦合文件。 - - - 确定性的钩子强制执行模型永远不能违反的规则。它们能挺过上下文压缩，而 - 配置文件中的自然语言规则则不能。 - - - -## 问题所在 - -大语言模型是无状态的 —— 每次调用只有一个上下文窗口，之后就会被清空。 - -- 它对你团队已经学到的东西**没有记忆**。 -- 它对一次编辑会破坏什么**没有预见**。 -- 它**没有强制执行的护栏** —— 自然语言的规则在一次压缩之后就会被遗忘。 - -而且每个工具都想要它自己的配置文件（`CLAUDE.md`、`AGENTS.md`、`.cursor/rules`、 -`GEMINI.md`、MCP……）。Forge 就是那层认知基底，补上这三样缺失的东西， -并作为编译器，从一份来源把它们分发到每个工具。 - -## 核心论点 - -模型无法在两次调用之间从你的代码库里学到东西：它的权重被冻结，工作记忆也 -在每次响应之后被清空。记忆、预见和自我检查 -无法通过提示词灌进去 —— 它们必须从 _外部_ 提供。那层外部东西 -就是认知基底。形式化地说，推理是一个固定的函数 `y = f(x)`，两次调用之间没有 -状态；Forge 就是那份状态。 - - - - 把你的规则和基底默认值写在一份规范来源里 - （`source/rules.json`、`source/substrate.json`、`source/mcp.json`）。 - - - `forge sync` 把这份来源编译成每个工具的原生配置 —— 九个 AI 编码 - 工具加上 MCP —— 带一个内容哈希头，所以漂移是可探测的，重复运行 - 是幂等的。 - - - `forge substrate ""` 运行一次确定性的动作前检查：假设、 - 路由、复用、上下文、爆炸半径、范围和目标锚点。 - - - 只有独立的裁决者 —— 测试、CI、人的接受/回退 —— 才能移动记忆 - 的置信度，所以错误的经验会衰减掉，而不是被固化下来。 - - - -## 你会得到什么 - -- **在会话之间和团队成员之间持续存在的记忆。** 每一条经验、事实和 - 已验证的复用都是 _proof-carrying memory (PCM)_ —— 我们给以证据为依据、 - 按内容寻址的记忆起的名字：一个声明，携带着它所依据的证据引用，只有当独立 - 裁决者把它的置信度抬升到某个底线之上时才被信任。"proof"（证据）指的是 - 这条证据链，而不是形式化证明。 -- **在把东西弄坏之前的预见能力。** 问一句"改动 `verifyToken` 会破坏什么？" - 就能从代码图里得到爆炸半径，包括你从未点名的耦合文件。 -- **不会被遗忘的护栏。** 确定性的钩子强制保护路径、 - 成本预算和死循环检测 —— 它们能挺过上下文压缩。 -- **从头到尾能够完成的工作。** 一个完成门在每个会话中会阻塞一次"完成" - —— 当代码动了但没有对应的文档或状态产物跟进时，答复里就带着修复清单。 -- **一份配置服务 9 个工具。** 规则只写一次；Forge 会输出每个工具的原生 - 配置，加上给 Roo 和 VS Code 的 MCP。零运行时依赖 —— 一个 Node CLI， - git 里的纯文本文件，不需要服务器。 - -## Forge 给哪些工具喂配置？ - -Forge 为**九个工具**输出配置，加上给 Roo Code 和 VS Code 的一个 MCP 服务器： -Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf/Devin、Zed 和 Continue。 -每个工具从它自己的原生文件里读同一份规则。 - -默认接通的 MCP 服务器只有 Forge 自己的那一个（`src/cortex_mcp.js`）—— 负责基底 -检查和记忆读取。像 `context7` 这样的第三方 MCP 服务器是**按需接入**（opt-in）的， -在你执行 [`forge integrations add --yes`](/cn/cli/config#forge-integrations) 之前， -它们绝不会落到磁盘上。 - -## 诚实的边界 - -Forge 到处都会声明它自己的天花板。 - - - Forge **减轻但不消除**规则漂移。它是一层透明度和可靠性 - 的加成，不能取代测试、评审或判断。 - - -- **护栏只能强制那些能表达成钩子的规则**（路径、格式、diff 大小、 - 预算）。语义规则（"偏好函数式"）仍然是自然语言，有时会被忽略。 -- **验证是减轻，不是认证。** Crew 验证者和幻觉符号 - 标记能减少评审负担；它们并不证明代码是正确的。 -- **不做权重级别的学习。** `recall` / `cortex` 只是文件加提示词的记忆 —— 没有 - RL，没有微调。 -- **影响图是基于正则的近似** —— 保守，但不是严格意义上的调用图。 -- **测试和人的修正永远拥有最终发言权。** - - - Forge 目前是 **beta** 阶段。核心（`init`、`sync`、`substrate`、`impact`、`ledger`、护栏） - 已经过测试并在日常使用中；一些标志可能会在 `1.0` 前变化。 - - -## 下一步 - - - - 安装，运行 `forge init`，然后让你的第一个任务过一次基底。 - - - 四层编译器、携带证据的记忆和动作前门。 - - - 每一条命令，按 Core、Memory、Substrate、Quality 和 Config 分组。 - - - 把队友的账本无冲突地合进来，走的是普通的 git。 - - diff --git a/mintlify/cn/quickstart.mdx b/mintlify/cn/quickstart.mdx deleted file mode 100644 index 321b955..0000000 --- a/mintlify/cn/quickstart.mdx +++ /dev/null @@ -1,106 +0,0 @@ ---- -title: "快速开始" -description: "安装 Forge，从一份来源为每个工具生成配置，然后运行你的第一次动作前检查 —— 大约需要 60 秒。" ---- - -大约一分钟内，从零走到一个配置完毕的仓库，并跑完你的第一次基底检查。 - -## 1. 安装 - - - -```bash Plugin (Claude Code / Codex) -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit -``` - -```bash npm (any tool) -npm install -g @codewithjuber/forgekit -``` - -```bash No registry -npm install -g github:CodeWithJuber/forgekit -``` - - - -对 Claude Code 和 Codex，推荐走插件路径 —— 护栏会自动接通， -没有什么需要手动合并。完整的方案矩阵，包括开发用的软链接方式，见 -[安装](/cn/installation)。 - -## 2. 配置一个仓库 - - - - ```bash - cd ~/your-project - forge init - ``` - 这会生成 `AGENTS.md`、`CLAUDE.md`、`.gemini/settings.json`、`.aider.conf.yml` 等 - 文件 —— 以及账本所需的 `.gitattributes` union-merge 规则。Claude Code、 - Codex、Cursor、Gemini、Aider、Copilot、Windsurf、Zed 和 Continue 现在都从各自的 - 原生文件里读**同一份**规则。 - - - ```bash - forge doctor - ``` - 对已安装工具、护栏、MCP 认证和配置漂移做一次通过/失败检查。 - - - 编辑 `source/rules.json`（或者放一份仓库级的 `.forge/rules.json`），然后重新编译： - ```bash - forge sync - ``` - `sync` 是幂等的 —— 只会重写发生变化的部分。 - - - -## 3. 运行动作前门 - -基底就是那层在模型编辑代码之 _前_ 运行的东西。一条命令跑完整个门： - -```bash -forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" -# → assumption verdict · cheapest capable model · predicted blast radius -# (including files you didn't name) · scope clusters · verification checklist -``` - - - 在 Claude Code 上，基底会通过 `UserPromptSubmit` 钩子在**每次提示上自动**运行 —— - 只是建议性的，对干净的任务保持静默。其他所有工具都会拿到一条原生配置规则， - 加上 19 个可以自行调用的 MCP 工具。 - - -如果 `forge substrate` 返回 `ASK FIRST`，在编辑前先问它返回的问题。在做任何 -修改性变更之前，先读一读预测的受影响文件 —— 即爆炸半径。 - -```bash -forge substrate "" --json # machine-readable verdict -forge impact # the blast radius on its own -``` - -## 4. 探索附加功能 - -```bash -forge atlas build # index this repo's symbols → .forge/atlas.json -forge atlas query useAuth # where is it defined? (cheaper than grep-and-read) -forge atlas has useAuth # does it exist? "not found" = likely hallucinated -forge recall add "db port" "Postgres is on 5433 here, not 5432" -forge catalog # the Start-Here index of everything -``` - -## 5. 第二天：账本正在学习 - -第一天基底学到的所有东西，都以声明的形式落到了 `.forge/ledger/`。这 -就是携带证据的记忆 —— 从现在开始它要开始回报你了： - -```bash -forge ledger stats # what the repo knows, by kind and trust -forge ledger blame # who minted a claim, every oracle outcome -forge reuse query "" # verified code you already have -``` - - - 阅读动作前门如何把它的各个阶段组合成一个统一的裁决。 - diff --git a/mintlify/docs.json b/mintlify/docs.json index 5229a26..b4211bd 100644 --- a/mintlify/docs.json +++ b/mintlify/docs.json @@ -19,7 +19,6 @@ "languages": [ { "language": "en", - "default": true, "tabs": [ { "tab": "Documentation", @@ -27,7 +26,11 @@ "groups": [ { "group": "Get started", - "pages": ["introduction", "quickstart", "installation"] + "pages": [ + "introduction", + "quickstart", + "installation" + ] }, { "group": "Core concepts", @@ -79,352 +82,11 @@ "groups": [ { "group": "Changelog", - "pages": ["changelog/overview"] - } - ] - } - ] - }, - { - "language": "cn", - "tabs": [ - { - "tab": "文档", - "icon": "book-open", - "groups": [ - { - "group": "开始使用", - "pages": ["cn/introduction", "cn/quickstart", "cn/installation"] - }, - { - "group": "核心概念", - "pages": [ - "cn/concepts/config-compiler", - "cn/concepts/proof-carrying-memory", - "cn/concepts/pre-action-gate", - "cn/concepts/cross-session-memory", - "cn/concepts/verification-gates", - "cn/concepts/model-routing" - ] - } - ] - }, - { - "tab": "CLI 参考", - "icon": "terminal", - "groups": [ - { - "group": "参考", - "pages": [ - "cn/cli/overview", - "cn/cli/core", - "cn/cli/memory", - "cn/cli/substrate", - "cn/cli/quality", - "cn/cli/config" - ] - } - ] - }, - { - "tab": "指南", - "icon": "compass", - "groups": [ - { - "group": "指南", - "pages": [ - "cn/guides/zero-config-onboarding", - "cn/guides/team-memory", - "cn/guides/radar-deps" - ] - } - ] - }, - { - "tab": "更新日志", - "icon": "newspaper", - "groups": [ - { - "group": "更新日志", - "pages": ["cn/changelog/overview"] - } - ] - } - ] - }, - { - "language": "ar", - "tabs": [ - { - "tab": "التوثيق", - "icon": "book-open", - "groups": [ - { - "group": "ابدأ", - "pages": ["ar/introduction", "ar/quickstart", "ar/installation"] - }, - { - "group": "المفاهيم الأساسية", - "pages": [ - "ar/concepts/config-compiler", - "ar/concepts/proof-carrying-memory", - "ar/concepts/pre-action-gate", - "ar/concepts/cross-session-memory", - "ar/concepts/verification-gates", - "ar/concepts/model-routing" - ] - } - ] - }, - { - "tab": "مرجع CLI", - "icon": "terminal", - "groups": [ - { - "group": "المرجع", - "pages": [ - "ar/cli/overview", - "ar/cli/core", - "ar/cli/memory", - "ar/cli/substrate", - "ar/cli/quality", - "ar/cli/config" - ] - } - ] - }, - { - "tab": "الأدلة", - "icon": "compass", - "groups": [ - { - "group": "الأدلة", - "pages": [ - "ar/guides/zero-config-onboarding", - "ar/guides/team-memory", - "ar/guides/radar-deps" - ] - } - ] - }, - { - "tab": "سجل التغييرات", - "icon": "newspaper", - "groups": [ - { - "group": "سجل التغييرات", - "pages": ["ar/changelog/overview"] - } - ] - } - ] - }, - { - "language": "hi", - "tabs": [ - { - "tab": "दस्तावेज़", - "icon": "book-open", - "groups": [ - { - "group": "शुरू करें", - "pages": ["hi/introduction", "hi/quickstart", "hi/installation"] - }, - { - "group": "मूल अवधारणाएँ", "pages": [ - "hi/concepts/config-compiler", - "hi/concepts/proof-carrying-memory", - "hi/concepts/pre-action-gate", - "hi/concepts/cross-session-memory", - "hi/concepts/verification-gates", - "hi/concepts/model-routing" + "changelog/overview" ] } ] - }, - { - "tab": "CLI संदर्भ", - "icon": "terminal", - "groups": [ - { - "group": "संदर्भ", - "pages": [ - "hi/cli/overview", - "hi/cli/core", - "hi/cli/memory", - "hi/cli/substrate", - "hi/cli/quality", - "hi/cli/config" - ] - } - ] - }, - { - "tab": "गाइड", - "icon": "compass", - "groups": [ - { - "group": "गाइड", - "pages": [ - "hi/guides/zero-config-onboarding", - "hi/guides/team-memory", - "hi/guides/radar-deps" - ] - } - ] - }, - { - "tab": "चेंजलॉग", - "icon": "newspaper", - "groups": [ - { - "group": "चेंजलॉग", - "pages": ["hi/changelog/overview"] - } - ] - } - ] - }, - { - "language": "zh-CN", - "tabs": [ - { - "tab": "文档", - "icon": "book-open", - "groups": [ - { - "group": "开始使用", - "pages": [ - "zh-CN/introduction", - "zh-CN/quickstart", - "zh-CN/installation" - ] - }, - { - "group": "核心概念", - "pages": [ - "zh-CN/concepts/config-compiler", - "zh-CN/concepts/proof-carrying-memory", - "zh-CN/concepts/pre-action-gate", - "zh-CN/concepts/cross-session-memory", - "zh-CN/concepts/verification-gates", - "zh-CN/concepts/model-routing" - ] - } - ] - }, - { - "tab": "CLI 参考", - "icon": "terminal", - "groups": [ - { - "group": "参考", - "pages": [ - "zh-CN/cli/overview", - "zh-CN/cli/core", - "zh-CN/cli/memory", - "zh-CN/cli/substrate", - "zh-CN/cli/quality", - "zh-CN/cli/config" - ] - } - ] - }, - { - "tab": "指南", - "icon": "compass", - "groups": [ - { - "group": "指南", - "pages": [ - "zh-CN/guides/zero-config-onboarding", - "zh-CN/guides/team-memory", - "zh-CN/guides/radar-deps" - ] - } - ] - }, - { - "tab": "更新日志", - "icon": "newspaper", - "groups": [ - { - "group": "更新日志", - "pages": ["zh-CN/changelog/overview"] - } - ] - } - ] - }, - { - "language": "zh-Hans", - "tabs": [ - { - "tab": "文档", - "icon": "book-open", - "groups": [ - { - "group": "开始使用", - "pages": [ - "zh-Hans/introduction", - "zh-Hans/quickstart", - "zh-Hans/installation" - ] - }, - { - "group": "核心概念", - "pages": [ - "zh-Hans/concepts/config-compiler", - "zh-Hans/concepts/proof-carrying-memory", - "zh-Hans/concepts/pre-action-gate", - "zh-Hans/concepts/cross-session-memory", - "zh-Hans/concepts/verification-gates", - "zh-Hans/concepts/model-routing" - ] - } - ] - }, - { - "tab": "CLI 参考", - "icon": "terminal", - "groups": [ - { - "group": "参考", - "pages": [ - "zh-Hans/cli/overview", - "zh-Hans/cli/core", - "zh-Hans/cli/memory", - "zh-Hans/cli/substrate", - "zh-Hans/cli/quality", - "zh-Hans/cli/config" - ] - } - ] - }, - { - "tab": "指南", - "icon": "compass", - "groups": [ - { - "group": "指南", - "pages": [ - "zh-Hans/guides/zero-config-onboarding", - "zh-Hans/guides/team-memory", - "zh-Hans/guides/radar-deps" - ] - } - ] - }, - { - "tab": "更新日志", - "icon": "newspaper", - "groups": [ - { - "group": "更新日志", - "pages": ["zh-Hans/changelog/overview"] - } - ] } ] } diff --git a/mintlify/hi/changelog/overview.mdx b/mintlify/hi/changelog/overview.mdx deleted file mode 100644 index 33776f9..0000000 --- a/mintlify/hi/changelog/overview.mdx +++ /dev/null @@ -1,60 +0,0 @@ ---- -title: "चेंजलॉग: Forge के नवीनतम रिलीज़ और अपडेट का विवरण" -description: "Forge में नया क्या है — नवीनतम रिलीज़, सुधार, वेरिफिकेशन गेट में बदलाव, नई सुविधाएँ, और डेवलपर वर्कफ़्लो अपडेट का पूरा विवरण यहाँ पढ़ें।" ---- - - - -## अपडेट - -**`forge verify --deep` अब चार-स्थिति वाला परिणाम रिपोर्ट करता है।** मल्टी-लेंस -कंसेंसस रन अब बाइनरी पास/फेल में सिमटकर नहीं रह जाता। आपको `PASS`, `FAIL`, -`INCOMPLETE`, या `NOT_CONFIGURED` में से एक दिखाई देगा, ताकि कोई अटका हुआ लेंस -या अनकॉन्फ़िगर्ड रेपो चुपचाप हरा न पढ़ा जा सके। केवल `PASS` को ही वेरिफाइड माना -जाता है, और अब `PASS` के लिए यह भी आवश्यक है कि अंतर्निहित `forge verify` -टेस्ट स्थिति `PASS` हो — एक हरा डीप रन कभी भी लाल बेस रन से आगे नहीं निकल सकता। - -देखें [Quality commands](/hi/cli/quality) और -[Verification gates](/hi/concepts/verification-gates)। - -**कोड परिवर्तनों के लिए कंप्लीशन गेट को टेस्ट साक्ष्य की आवश्यकता है।** किसी भी -ऐसे सेशन के लिए जिसने सोर्स कोड को छुआ हो, Stop-path कंप्लीशन गेट अब अकेले -`forge handoff` स्नैपशॉट को स्वीकार नहीं करता। आपको या तो सेशन के डिफ़ में एक -टेस्ट फ़ाइल की आवश्यकता होगी, या मौजूदा परिवर्तनों के विरुद्ध एक ताज़ा पासिंग -`forge verify` की। केवल-दस्तावेज़, केवल-कॉन्फ़िग, और अन्य गैर-कोड सेशन प्रभावित -नहीं होते। - -जब गेट ब्लॉक करता है, तो रिपेयर चेकलिस्ट अब `forge verify` से शुरू होती है ताकि -हैंडऑफ़ स्नैपशॉट से पहले साक्ष्य दर्ज हो जाए। देखें -[Cross-session memory](/hi/concepts/cross-session-memory)। - -**हुक्स और गार्डरेल्स के लिए स्पष्ट पोज़िशनिंग।** Forge के ऑटोमैटिक हुक्स -`Claude Code`-विशिष्ट हैं, और — बाकी हर सलाहकार सिग्नल की तरह — जब तक आप -`FORGE_ENFORCE=1` के साथ ऑप्ट-इन नहीं करते, तब तक वे डिफ़ॉल्ट रूप से बंद रहते -हैं। गार्डरेल्स डिफेंस-इन-डेप्थ हैं, कोई सिक्योरिटी सैंडबॉक्स नहीं। रनटाइम में -कुछ भी नहीं बदला है; बस डॉक्स और CLI कॉपी अब वही कहती हैं जो टूल असल में करता -है। देखें [CLI overview](/hi/cli/overview) और -[Pre-action gate](/hi/concepts/pre-action-gate)। - -## फ़िक्स - -**सीक्रेट रिडैक्टर अब स्ट्रक्चर्ड टूल आउटपुट को सुरक्षित रखता है।** `Bash`, -`Read`, और `Grep` जैसे बिल्ट-इन टूल्स स्ट्रक्चर्ड ऑब्जेक्ट्स लौटाते हैं, और -पिछला रिडैक्टर उन रेस्पॉन्सेस को स्ट्रिंगिफ़ाई कर देता था — जिसका अर्थ था कि -`Claude Code` चुपचाप रीराइट को छोड़ देता और बिना रिडैक्ट किया आउटपुट दिखता -रहता। अब रिडैक्टर रेस्पॉन्स में रिकर्सिवली चलता है: स्ट्रिंग्स को उसी जगह -स्क्रब किया जाता है, ऐरे और ऑब्जेक्ट अपनी कीज़ और आकार बनाए रखते हैं, और -गैर-स्ट्रिंग लीफ़्स अछूती पास होती हैं। सादे-स्ट्रिंग रेस्पॉन्सेस बाइट-दर-बाइट -पहले जैसे ही रिडैक्ट होते हैं, और जिस रेस्पॉन्स में रिडैक्ट करने को कुछ नहीं -है, उसके लिए कोई रीराइट जारी नहीं होता। - -**`FORGE_GUARD_STRICT=1` का एग्ज़िट स्टेटस अब निगला नहीं जाता।** रिडैक्टर का -शेल रैपर पहले क्लीन एग्ज़िट फ़ोर्स करता था, जिससे स्ट्रिक्ट-मोड का फ़ेल्योर -कोड `Claude Code` से छिप जाता और `DEGRADED` सिग्नल कभी सामने नहीं आता था। अब -चाइल्ड का एग्ज़िट स्टेटस एंड-टू-एंड प्रोपेगेट किया जाता है, जिससे स्ट्रिक्ट -मोड का stderr फ़ीडबैक असल में आप तक पहुँचता है। ध्यान दें कि यह हुक टूल के -पहले ही चल जाने के बाद चलता है — स्ट्रिक्ट मोड रिडैक्टर के डिग्रेडेशन को -मुखर बनाता है, लेकिन किसी कॉल को चलने से पहले रोकना -[Pre-action gate](/hi/concepts/pre-action-gate) का काम है। - - diff --git a/mintlify/hi/cli/config.mdx b/mintlify/hi/cli/config.mdx deleted file mode 100644 index cc7cb14..0000000 --- a/mintlify/hi/cli/config.mdx +++ /dev/null @@ -1,163 +0,0 @@ ---- -title: "Config कमांड्स" -description: "प्रोवाइडर्स, लागत, डैशबोर्ड्स, ब्रांड, atlas, स्टैक और ऑप्ट-इन MCP इंटीग्रेशन्स: config, cost, dash, brand, atlas, stack, report, tools, integrations।" ---- - -Config समूह प्रोवाइडर्स, ऑब्ज़र्वेबिलिटी, कोड ग्राफ़, और स्टैक डिटेक्शन को कवर करता है। - -## `forge config` - -प्रोवाइडर सेटअप — प्रोवाइडर्स दिखाएँ / स्विच करें / जोड़ें, डिफ़ॉल्ट मॉडल सेट करें। - -```bash -forge config # show current config -forge config switch -forge config add -``` - -## `forge cost` - -मापित स्टेज फ़ैक्टर्स के माध्यम से वास्तविक प्रति-दिन खर्च। - -```bash -forge cost # real per-day spend -forge cost --stages # measured per-stage cost factors -``` - - - **केवल मापित चरणों** की रिपोर्ट करता है — बिना घटनाओं वाला चरण "no data" कहता है, - कभी कोई डिफ़ॉल्ट नहीं। - - -## `forge dash` - -लेजर, मीट्रिक्स, और ब्लास्ट रेडियस पर लोकल डैशबोर्ड। - -```bash -forge dash # localhost-only (default port 4242) -``` - -## `forge brand` - -सक्रिय ब्रांड टोकन मैप प्रिंट करें। - -```bash -forge brand -``` - -ब्रांड एक टोकन (`brand.json`) के रूप में संग्रहीत है; रीब्रांड एक ही संपादन है। - -## `forge atlas` - -कोड ग्राफ़ बनाएँ / क्वेरी करें। - -```bash -forge atlas build [path] # walk the tree → .forge/atlas.json -forge atlas query "what calls Z" -forge atlas has # hallucinated-symbol check -``` - -atlas सादा JSON है — कोई भी टूल पढ़ता है, MCP आवश्यक नहीं। - -## `forge stack` - -इस रेपो के मैनिफ़ेस्ट से इसका वास्तविक स्टैक पहचानें। - -```bash -forge stack -``` - -`package.json`, `pyproject.toml`, `go.mod`, `Cargo.toml`, `Gemfile`, -`composer.json`, `pom.xml` / `build.gradle`, और `*.csproj` पढ़ता है, और भाषाएँ, -फ़्रेमवर्क, पैकेज मैनेजर, और रेपो की **वास्तविक** टेस्ट कमांड्स रिपोर्ट करता है — जो -सब्सट्रेट की सत्यापन चेकलिस्ट को फ़ीड करते हैं। - -## `forge report` - -रेपो की Forge स्थिति की एक स्टैटिक HTML रिपोर्ट बनाएँ — लेजर, मीट्रिक्स, और ब्लास्ट -रेडियस एक स्व-निहित फ़ाइल में प्रस्तुत जिसे आप साझा या संग्रह कर सकते हैं। - -```bash -forge report -``` - -## `forge tools` - -इस रेपो का प्राथमिक AI कोडिंग टूल चुनें और मिलती-जुलती `.gitignore` प्रविष्टियाँ वायर करें, -ताकि आपके सेटअप के लिए जनरेट की गई कॉन्फ़िग और `.forge/` आर्टिफ़ैक्ट सही ढंग से अनदेखे हों। - -```bash -forge tools -``` - -## `forge integrations` - -ऑप्ट-इन थर्ड-पार्टी MCP सर्वर (उदाहरण के लिए `context7`), हर उस टूल में गैर-विनाशकारी -ढंग से प्रबंधित जिसके लिए Forge कॉन्फ़िग निकालता है — Claude Code, Codex, Cursor, -Gemini, Continue, और बाकी सभी। - -थर्ड-पार्टी MCP सर्वर डिफ़ॉल्ट रूप से इंस्टॉल **नहीं** होते। जब तक आप -`forge integrations add --yes` नहीं चलाते तब तक डिस्क पर कुछ नहीं उतरता। - -```bash -forge integrations # list opt-in servers with package + purpose -forge integrations add # dry-run: prints package, network, files it would touch -forge integrations add --yes # apply — write MCP config for every tool -forge integrations add --yes --adopt # also claim a same-name entry you already configured -forge integrations remove # reverse the add — deletes only forge-owned entries -``` - -### `add` क्या लिखता है - -`add --yes` एक कैननिकल स्पेक से हर टूल की नेटिव MCP कॉन्फ़िग में सर्वर लिखता है: - -- `.mcp.json` (Claude Code) -- `.cursor/mcp.json` (Cursor) -- `.gemini/settings.json` (Gemini) -- `.codex/config.toml` — एक `# forge:managed:` ब्लॉक के रूप में, बाइट-तुलना द्वारा रीफ़्रेश -- `.continue/mcpServers/.yaml` — प्रति प्रबंधित सर्वर एक forge-चिह्नित YAML -- और बाकी वे टूल्स जिनके लिए Forge कॉन्फ़िग निकालता है - -इंस्टॉल किया गया सेट `.forge/forge.config.json` में `mcp.integrations` के तहत दर्ज होता है, -ताकि हर आगामी `forge sync` वही सर्वर पुनः निकाले। स्टॉप-हुक ऑटो-सिंक पूरी कॉन्फ़िग फ़ाइल की -बाइट-तुलना करता है, इसलिए उस फ़ाइल में हाथ से किया गया एडिट पहचाना जाता है और सुधार दिया जाता है। - -### `--adopt` सिमैंटिक्स - -अगर किसी टूल की कॉन्फ़िग फ़ाइल में उसी नाम का सर्वर पहले से मौजूद है और उसे Forge ने -वहाँ नहीं रखा, तो `add` उसे **ओवरराइट नहीं करता**। इसके बजाय वह फ़ाइल को `--adopt` संकेत -के साथ रिपोर्ट करता है। स्वामित्व लेने के लिए `--adopt` के साथ पुनः चलाएँ — Forge उस -प्रविष्टि को `.forge/forge.config.json` में `mcp.adopted` के तहत दर्ज करता है और उसके बाद -से उसे प्रबंधित करता है। - -`--adopt` का उपयोग तब करें जब आपने पहले हाथ से किसी सर्वर को कॉन्फ़िगर किया था और अब -चाहते हैं कि Forge उसे हर टूल में सिंक रखे। - -### `remove` - -`forge integrations remove ` एक add को उलट देता है। यह केवल forge-स्वामित्व वाली -प्रविष्टियाँ, ब्लॉक और फ़ाइलें हटाता है — उपयोगकर्ता द्वारा कॉन्फ़िगर किया गया (और कभी -`--adopt` न किया गया) उसी नाम का सर्वर अछूता छोड़ दिया जाता है। `remove` दो बार चलाना -नो-ऑप है। - -```bash -forge integrations remove context7 -``` - -### `.forge/forge.config.json` - -प्रति-रेपो Forge स्टेट — वही यूनिफ़ाइड कॉन्फ़िग जो `primaryTool`, `tools`, और `profile` -भी रखती है — ऑप्ट-इन इंटीग्रेशन को दो कुंजियों के तहत दर्ज करती है: - -```json -{ - "mcp": { - "integrations": ["context7"], - "adopted": [] - } -} -``` - -अज्ञात कुंजियाँ राइट्स के दौरान राउंड-ट्रिप करती हैं। खराब फ़ॉर्मैट वाली फ़ाइल चुपचाप -नहीं छोड़ी जाती: रीड्स प्रति प्रक्रिया एक बार stderr पर चेतावनी देते हैं, और राइटर्स -किसी अपार्सेबल कॉन्फ़िग को डिफ़ॉल्ट्स से बदलने के बजाय उस पर लिखने से इनकार कर देते हैं। diff --git a/mintlify/hi/cli/core.mdx b/mintlify/hi/cli/core.mdx deleted file mode 100644 index 40913b1..0000000 --- a/mintlify/hi/cli/core.mdx +++ /dev/null @@ -1,114 +0,0 @@ ---- -title: "Core कमांड्स" -description: "Forge रेपो को init, sync, doctor, catalog, docs, और update से बूटस्ट्रैप और रखरखाव करें — साथ ही profile, settings, और reversible-uninstall फ़्लैग।" ---- - -Core समूह एक रेपो को बूटस्ट्रैप करता है और उसे स्वस्थ रखता है। - -## `forge init` - -इस रेपो का कॉन्फ़िग स्कैफ़ोल्ड करें — एक साझा स्रोत से हर टूल का कॉन्फ़िग निकालता है। - -```bash -forge init -``` - -`AGENTS.md`, `CLAUDE.md`, `.gemini/settings.json`, `.aider.conf.yml`, और बाकी -निकालता है (साथ ही Roo Code और VS Code के लिए MCP सर्वर कॉन्फ़िग), और लेजर के लिए -आवश्यक `.gitattributes` यूनियन-मर्ज नियम। - -`forge init` Forge के हुक्स और अनुमतियों को **ग्लोबल** `~/.claude/settings.json` -में भी मर्ज करता है, इसलिए यह लिखने से पहले मर्ज की घोषणा करता है। मर्ज -idempotent है, मार्कर-गार्डेड है, और उपयोगकर्ता की प्रविष्टियों को कभी नहीं मिटाता। - -### Init फ़्लैग - -| फ़्लैग | यह क्या करता है | -| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--profile ` | इस रेपो के लिए पॉलिसी प्रोफ़ाइल चुनें। `minimal` या `standard` (डिफ़ॉल्ट) स्वीकार करता है। अमान्य मान किसी भी स्कैफ़ोल्ड, `.forge/` राइट, या मर्ज से पहले ही निरस्त कर देता है। | -| `--no-settings` | ग्लोबल `~/.claude/settings.json` मर्ज को पूरी तरह छोड़ दें — केवल प्रति-रेपो कॉन्फ़िग लिखा जाता है। | -| `--remove-settings` | किसी पिछले settings मर्ज को उलटें। Forge-आकार के हुक्स, अनुमतियाँ, statusline, और `_forge` मार्कर हटा दिए जाते हैं; पहले एक टाइमस्टैम्प वाला बैकअप लिखा जाता है, और आपकी अपनी प्रविष्टियाँ संरक्षित रहती हैं। `install.sh --uninstall` द्वारा भी आह्वान किया जाता है। | -| `--settings-only` | केवल ग्लोबल settings मर्ज करें — रेपो को न छुएँ। `install.sh` द्वारा हुक्स और अनुमतियाँ वायर करने के लिए उपयोग किया जाता है। | - -यदि settings मर्ज अस्वीकार किया जाता है या त्रुटि होती है, तो `forge init` सफलता की -रिपोर्ट करने के बजाय exit 1 के साथ विफल होता है और कारण को stderr पर लिखता है। - -### पॉलिसी प्रोफ़ाइल - -`--profile` वह रूलसेट चुनता है जिसे `forge sync` प्रत्येक टूल की नेटिव कॉन्फ़िग में -कंपाइल करता है। केवल दो प्रोफ़ाइल समर्थित हैं: - -- **`standard`** (डिफ़ॉल्ट) — पूरा पैक: साझा मेमोरी नियम, प्रभाव विश्लेषण, और - संपूर्ण गार्डरेल हुक सेट। -- **`minimal`** — छोटे रेपो या योगदानकर्ता फ़ॉर्क के लिए एक हल्का रूलसेट। - -पुराने नाम `web-app`, `backend-service`, `library`, और `regulated` `standard` के -पदावनत उपनाम हैं। वे अभी भी काम करते हैं: `forge init` एक बार चेतावनी देता है, -`standard` संग्रहीत करता है, और पुराने नाम धारण करने वाले मौजूदा कॉन्फ़िग standard के -रूप में sync होते हैं। नए रेपो को सीधे `standard` का उपयोग करना चाहिए। कोई भी अन्य -मान अमान्य है और Forge द्वारा रेपो को छूने से पहले ही निरस्त कर देता है। - -```bash -forge init --profile minimal # leaner ruleset -forge init --no-settings # per-repo only, skip the global merge -forge init --remove-settings # reverse a past global merge -``` - -## `forge sync` - -कैननिकल स्रोत को हर टूल की नेटिव कॉन्फ़िग फ़ाइलों में पुनः कंपाइल करें। - -```bash -forge sync -``` - -Idempotent — यह केवल वही पुनर्लिखित करता है जो बदला है। `source/rules.json` या -प्रति-रेपो `.forge/rules.json` संपादित करने के बाद इसे चलाएँ। - -## `forge doctor` - -इंस्टॉल किए गए टूल्स, गार्ड्स, MCP ऑथ, और कॉन्फ़िग ड्रिफ्ट की हेल्थ-चेक। - -```bash -forge doctor -``` - -टूल्स, गार्ड्स, MCP वायरिंग, कॉन्फ़िग ड्रिफ्ट, और अपडेट स्थिति पर पास/फ़ेल। हर पथ -fail-open है। जब कोई कस्टम gateway कॉन्फ़िगर हो तो एक **gateway models** पंक्ति -हल किए गए `tier → model` मैपिंग को प्रिंट करती है। - -## `forge catalog` - -Start Here — हर टूल, क्रू, और गार्ड को एक-पंक्ति कारण के साथ सूचीबद्ध करें। - -```bash -forge catalog -``` - -## `forge docs` - -Docs ↔ code ड्रिफ्ट। - -```bash -forge docs check # registry reconcile — commands, env vars, MCP tools, CHANGELOG -forge docs sync # diff-driven stale-docs sweep -``` - - - `docs check` CI को fail करता है जब कमांड्स, env vars, MCP टूल्स, या CHANGELOG - कोड से ड्रिफ्ट करते हैं। `docs sync` diff को स्वीप करता है और UPDATED / STALE / - VERIFIED-UNAFFECTED रिपोर्ट करता है। - - -## `forge update` - -तीनों इंस्टॉल मोड्स में सेल्फ़-अपडेट। - -```bash -forge update # apply the update (git checkout or npm/copy install) -forge update --check # report whether a newer version is available -forge update --to # pin or downgrade to a specific version -``` - -हर पथ fail-open है — ऑफ़लाइन, कोई upstream नहीं, या detached HEAD "unknown" लौटाता है, -कभी कोई error नहीं। `FORGE_NO_UPDATE_CHECK=1` doctor सूचना को शांत करता है। diff --git a/mintlify/hi/cli/memory.mdx b/mintlify/hi/cli/memory.mdx deleted file mode 100644 index 5cc429e..0000000 --- a/mintlify/hi/cli/memory.mdx +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "Memory कमांड्स" -description: "क्रॉस-सेशन और टीम मेमोरी: cortex, recall, remember, brain, ledger, reuse, handoff, और decide — ये सभी प्रूफ-कैरीइंग लेजर पर संगमित होते हैं।" ---- - -Memory समूह क्रॉस-सेशन और टीम मेमोरी का प्रबंधन करता है। इसकी सारी सामग्री -`.forge/ledger/` के प्रूफ-कैरीइंग लेजर पर संगमित होती है। मॉडल के लिए -[Proof-carrying memory](/hi/concepts/proof-carrying-memory) देखें। - -## `forge cortex` - -स्व-सुधार करने वाली प्रोजेक्ट मेमोरी — सुधारों से खनन किए गए सबक। - -```bash -forge cortex status # what's been learned -forge cortex why # why a lesson applies here -``` - -## `forge recall` - -क्रॉस-सेशन व्यक्तिगत मेमोरी प्रबंधित करें। - -```bash -forge recall list # facts the recall-load guard injects next session -forge recall add "db port" "Postgres is on 5433 here, not 5432" -forge recall consolidate # summarize (advisory, human-reviewable) -``` - -## `forge remember` - -इस रेपो की पोर्टेबल मेमोरी में एक टिकाऊ, रेपो-कमिटेबल तथ्य जोड़ें। - -```bash -forge remember "" -``` - -## `forge brain` - -पोर्टेबल प्रोजेक्ट-मेमोरी इंडेक्स दिखाएँ या पुनर्निर्मित करें। - -```bash -forge brain # show the index -forge brain --rebuild # rebuild it -``` - -## `forge ledger` - -प्रूफ-कैरीइंग मेमोरी — कंटेंट-एड्रेस्ड क्लेम स्टोर। - -```bash -forge ledger stats # what the repo knows, by kind and trust level -forge ledger verify # re-check claims are in normal form -forge ledger show # a claim and its evidence -forge ledger blame # who minted it, every oracle outcome, per-author trust -forge ledger query "" # retrieve by relevance -forge ledger ratify # human accept -forge ledger retract # tombstone a claim -forge ledger merge # fold a teammate's ledger in, conflict-free -forge ledger import # back-fill pre-ledger history into the ledger -``` - -प्रति-यूज़र लेजर के लिए `--personal` जोड़ें। - -## `forge reuse` - -प्रूफ-कैरीइंग कोड कैश — केवल तब सर्व किया जाता है जब उसका साक्ष्य अब भी वैध हो। - -```bash -forge reuse query "" # verified code you already have -forge reuse mint "" --file # add an artifact to the cache -forge reuse stats # cache stats -``` - -## `forge handoff` - -सीमित सत्र स्नैपशॉट — `.forge/state.md` को पुनर्लिखता है, हर सत्र-आरंभ पर पुनः इंजेक्ट किया जाता है। - -```bash -forge handoff "" --next "" -``` - -## `forge decide` - -केवल-जोड़ने-वाला निर्णय लॉग — `.forge/decisions.md` में `D-####` ADR-lite प्रविष्टियाँ। - -```bash -forge decide " — " -forge decide # read the log before re-deciding -``` - -## `forge know` - -किसी तथ्य को उसके सही स्टोरेज गंतव्य पर रूट करें — यह तय करता है कि ज्ञान का एक टुकड़ा -`recall`, `remember`/`brain`, एक निर्णय, या एक cortex सबक में रहना चाहिए, और उसे वहाँ दर्ज करता है। - -```bash -forge know "" -``` - -## `forge deja` - -समान-पिछले-कार्य की खोज — लेजर में पूर्व कार्य को सतह पर लाता है जो उससे मेल खाता है -जो आप करने वाले हैं, ताकि आप पुनर्जनन के बजाय प्रमाण का पुनरुपयोग करें। - -```bash -forge deja "" -``` diff --git a/mintlify/hi/cli/overview.mdx b/mintlify/hi/cli/overview.mdx deleted file mode 100644 index d8e1365..0000000 --- a/mintlify/hi/cli/overview.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: "CLI अवलोकन" -description: "हर forge कमांड Core, Memory, Substrate, Quality, और Config के अनुसार समूहित, साथ ही वे env vars जो प्रवर्तन और आउटपुट को नियंत्रित करते हैं।" ---- - -`forge` कमांड सतह डेटा (`src/commands.js`) के रूप में परिभाषित है और `forge docs check` -द्वारा डॉक्स के विरुद्ध सुलझाई जाती है, इसलिए कोई कमांड डॉक्स की जानकारी के बिना -न शिप हो सकती है, न ग़ायब हो सकती है। कमांड्स को पाँच समूहों में संगठित किया गया है। - - - - बूटस्ट्रैप और रखरखाव: `init`, `sync`, `doctor`, `catalog`, `docs`, `update`। - - - क्रॉस-सेशन और टीम मेमोरी: `cortex`, `recall`, `remember`, `brain`, `ledger`, - `reuse`, `handoff`, `decide`। - - - प्री-एक्शन गेट और उसके चरण: `substrate`, `preflight`, `route`, `impact`, - `scope`, `context`, `anchor`, `diagnose`, `imagine`, `lean`। - - - सत्यापन और सुरक्षा: `verify`, `scan`, `spec`, `taste`, `uicheck`, `harden`। - - - प्रोवाइडर्स, लागत, डैशबोर्ड्स, ब्रांड, atlas, स्टैक: `config`, `cost`, `dash`, `brand`, - `atlas`, `stack`। - - - -## परिपाटियाँ - -- **डिफ़ॉल्ट रूप से सलाहकारी।** सबसे मज़बूत संकेतों (खोखला प्रॉम्प्ट, असंयोजनीय - आवश्यक कॉन्टेक्स्ट, डिफ़ॉल्ट 25-फ़ाइल थ्रेशोल्ड से अधिक ब्लास्ट रेडियस) पर सब्सट्रेट - को हार्ड ब्लॉक में बदलने के लिए `FORGE_ENFORCE=1` सेट करें। -- **डिफ़ॉल्ट रूप से मौन।** प्रति-कमांड `Forge — …` शीर्षक `--verbose` / - `FORGE_VERBOSE` के पीछे ब्रांडिंग क्रोम है; एक कमांड पहले अपना परिणाम देती है। -- **पाइप-अनुकूल आउटपुट।** पाइप किए जाने पर सादा पाठ; TTY पर यह ब्रांड-पैलेट रंग और - कॉन्फ़िडेंस मीटर जोड़ता है। `NO_COLOR` रंग बंद करता है, `FORCE_COLOR=1` उसे बलपूर्वक चालू करता है। -- **`--json`** स्क्रिप्टिंग के लिए सब्सट्रेट और अधिकांश एनालिसिस कमांड्स पर उपलब्ध है। - -## एन्वायरनमेंट वेरिएबल्स - -| वेरिएबल | प्रभाव | -| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `FORGE_ENFORCE=1` | सब्सट्रेट के सबसे मज़बूत सलाहकारी संकेतों को हार्ड ब्लॉक में बदल दें। | -| `FORGE_GUARD_STRICT=1` | secret redactor की `DEGRADED` चेतावनी को एक ब्लॉकिंग exit में एस्केलेट करें। डिफ़ॉल्ट रूप से एक redaction विफलता stderr पर `secret redaction DEGRADED` प्रिंट करती है और आउटपुट को पास होने देती है; strict मोड कुछ भी उत्सर्जित करने से मना कर देता है जिसे redactor पूरी तरह स्क्रब नहीं कर सका। इसे CI में या साझा मशीनों पर उपयोग करें जहाँ एक बिना-redacted पंक्ति विफल कमांड से बुरा हो। | -| `FORGE_NO_UPDATE_CHECK=1` | `forge doctor` में "commits behind upstream" सूचना को शांत करें। | -| `FORGE_NO_HINT=1` | एक-बार आने वाला init संकेत मौन करें जो आपको `forge init` चलाने के लिए प्रेरित करता है। | -| `FORGE_VERBOSE=1` | प्रति-कमांड बैनर (`Forge — …`) दिखाएँ जो डिफ़ॉल्ट रूप से छिपा होता है। | -| `FORGE_EMBED=1` | मेमोरी recall के लिए एम्बेडिंग टियर में ऑप्ट-इन करें (MinHash शून्य-निर्भरता डिफ़ॉल्ट बना रहता है)। | -| `FORGE_LEDGER_ONLY=0` | एस्केप हैच। Ledger-only अब डिफ़ॉल्ट है — मेमोरी केवल `.forge/ledger` में रहती है, और पुरानी `lessons/*.md` + fact फ़ाइलें अब नहीं लिखी जातीं। पुराने फ़ाइल स्टोर को वापस लाने के लिए `0` सेट करें। | - - - हमेशा-अद्यतन सूची के लिए `forge --help` चलाएँ, या हर टूल, क्रू, और गार्ड के एक-पंक्ति - कारण के साथ Start-Here इंडेक्स के लिए `forge catalog`। - - -## नए कमांड्स और फ़्लैग - -ये कमांड्स और फ़्लैग उपलब्ध हैं। वे अपने समूह पृष्ठों पर प्रलेखित हैं -और इनलाइन फ़्लैग किए गए हैं: - -| कमांड / फ़्लैग | समूह | यह क्या करता है | -| ---------------------- | -------- | ----------------------------------------------- | -| `forge know` | Memory | किसी तथ्य को उसके सही स्टोरेज गंतव्य पर रूट करें। | -| `forge deja` | Memory | समान-पिछले-कार्य की खोज। | -| `forge precommit` | Quality | कमिट-स्तरीय सत्यापन गेट। | -| `forge radar` | Quality | निर्भरता-नवीनता रिंग्स। | -| `forge report` | Config | रेपो की Forge स्थिति की स्टैटिक HTML रिपोर्ट। | -| `forge tools` | Config | प्राथमिक-टूल चयन + gitignore वायरिंग। | -| `forge verify --deep` | Quality | मल्टी-लेंस सर्वसम्मति सत्यापन। | -| `forge update --to` | Core | किसी विशिष्ट संस्करण पर पिन या डाउनग्रेड करें। | diff --git a/mintlify/hi/cli/quality.mdx b/mintlify/hi/cli/quality.mdx deleted file mode 100644 index 6874f0e..0000000 --- a/mintlify/hi/cli/quality.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "Quality कमांड्स" -description: "Forge के quality CLI का reference: verify, scan, spec, taste, uicheck और harden कमांड्स।" ---- - -Quality समूह सत्यापन और सुरक्षा सतह है। ये कैसे संयोजित होते हैं इसके लिए -[Verification gates](/hi/concepts/verification-gates) देखें। - -## `forge verify` - -स्वतंत्र सत्यापन गेट — टेस्ट्स + हैलुसिनेटेड-सिंबल + provenance। - -```bash -forge verify -forge verify --deep # multi-lens consensus -``` - -`forge verify --deep` सामान्य pass/fail के बजाय एक चार-अवस्था वाला `status` रिपोर्ट करता है: - -| Status | अर्थ | -| ---------------- | ------------------------------------------------------------------------------------ | -| `PASS` | हर lens सहमत हुआ **और** core `forge verify` tests status भी `PASS` है। | -| `FAIL` | कम-से-कम एक lens ने वास्तविक failure रिपोर्ट किया। | -| `INCOMPLETE` | कोई lens पूरा नहीं हो सका (timeout, crash, missing dependency) — इसे unproven मानें। | -| `NOT_CONFIGURED` | इस repo के लिए कोई lenses wired नहीं हैं — असल में कुछ भी check नहीं हुआ। | - -केवल `PASS` को verified माना जाता है। `--deep` जानबूझकर consensus को `PASS` पर promote -करने से मना कर देता है जब अंतर्निहित `forge verify` tests status `PASS` के अलावा कुछ भी हो, इसलिए -एक हरा deep run हमेशा एक हरे base run का संकेत देता है। - -## `forge scan` - -Skill-गेट — इंस्टॉल से पहले किसी skill या MCP सर्वर की injection / RCE / exfil के लिए जाँच करें। - -```bash -forge scan -``` - -## `forge spec` - -Spec-as-contract — init (OpenSpec), lock, और drift जाँचें। - -```bash -forge spec init -forge spec lock -forge spec check -``` - -## `forge taste` - -इस रेपो के लिए एक UI-taste टूल सक्षम करें (कोई arg नहीं होने पर विकल्प सूचीबद्ध होते हैं)। - -```bash -forge taste # list the profiles -forge taste # brutalist · corporate · editorial · minimalist · playful -``` - -`DESIGN.md` लिखता है और `uicheck design` गेट थ्रेशोल्ड्स को पैरामीटराइज़ करता है। - -## `forge uicheck` - -डिटरमिनिस्टिक UI जाँचें। - -```bash -forge uicheck contrast # WCAG contrast ratio -forge uicheck fingerprint # deterministic design fingerprint -forge uicheck design # slop-distance + conformance gate -forge uicheck visual # Playwright-rendered check (opt-in tier) -``` - -## `forge harden` - -सुरक्षा नियंत्रण वायर करें — gitleaks pre-commit + sandbox सेटिंग्स। - -```bash -forge harden -``` - -## `forge precommit` - -कमिट-स्तरीय गेट — कमिट समय पर सत्यापन-न्यूनतम चलाता है ताकि आंशिक या असत्यापित कार्य -उतरने से पहले पकड़ा जा सके। - -```bash -forge precommit -``` - -## `forge radar` - -निर्भरता-नवीनता रिंग्स — प्रोजेक्ट की निर्भरताओं को उनकी नवीनता के अनुसार समूहित करता है, -ताकि पुरानी या बहती निर्भरताएँ नुक़सान पहुँचाने से पहले सतह पर आ जाएँ। - -```bash -forge radar -``` - -रिंग्स कैसे पढ़ें इसके लिए [Keeping dependencies current](/hi/guides/radar-deps) गाइड देखें। diff --git a/mintlify/hi/cli/substrate.mdx b/mintlify/hi/cli/substrate.mdx deleted file mode 100644 index 130789a..0000000 --- a/mintlify/hi/cli/substrate.mdx +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: "Substrate कमांड्स" -description: "प्री-एक्शन गेट और उसके व्यक्तिगत रूप से कॉल किए जाने योग्य चरण: substrate, preflight, route, impact, scope, context, anchor, diagnose, imagine, और lean।" ---- - -Substrate समूह प्री-एक्शन गेट है। `forge substrate` बाकी को एक ही वर्डिक्ट में संयोजित -करता है; प्रत्येक चरण को अकेले भी कॉल किया जा सकता है। पाइपलाइन के लिए -[The pre-action gate](/hi/concepts/pre-action-gate) देखें। - -## `forge substrate` - -एक प्री-एक्शन गेट: अनुमान, रूट, प्रभाव, स्कोप, मेमोरी, वेरीफ़ाई। - -```bash -forge substrate "" -forge substrate "" --json -``` - -यदि यह `okToProceed:false` लौटाता है, तो एडिट करने से पहले लौटाए गए `assumption.questions` पूछें। - -## `forge preflight` - -अनुमान जाँच — कोई कार्य क्या नाम लेता है जो रेपो परिभाषित नहीं करता। - -```bash -forge preflight "" -``` - -## `forge route` - -किसी कार्य के लिए सबसे सस्ते समर्थ मॉडल की सिफ़ारिश करें। - -```bash -forge route "" -forge route gateway # emit LiteLLM gateway config -``` - -## `forge impact` - -atlas ग्राफ़ से किसी सिंबल या फ़ाइल के लिए ब्लास्ट रेडियस का पूर्वानुमान लगाएँ। - -```bash -forge impact -``` - -## `forge scope` - -फ़ाइलों को स्वतंत्र क्लस्टर्स में विघटित करें — साथ ही युग्मित फ़ाइलें जिनका नाम आपने नहीं लिया। - -```bash -forge scope -``` - -## `forge context` - -बजट-सीमित कॉन्टेक्स्ट संयोजन + पूर्णता गेट — किसी एडिट को क्या जानना ज़रूरी है। - -```bash -forge context "" -``` - -पूर्वानुमानित एडिट सेट पर set-cover के माध्यम से बजट-सीमित कॉन्टेक्स्ट संयोजित करता है, -एक कंप्रेशन लैडर लागू करता है, और गणना किए गए missing set की रिपोर्ट करता है। - -## `forge anchor` - -लक्ष्य-ड्रिफ्ट जाँच — क्या आपके वास्तविक (git) परिवर्तन अभी भी बताए गए लक्ष्य पर हैं? - -```bash -forge anchor set "" # persist the goal across sessions -forge anchor show -forge anchor clear -``` - -## `forge diagnose` - -डूम-लूप जाँच — एक असफलता दर्ज करें; वही हस्ताक्षर 3× एक निदान + एस्केलेशन बनाता है। - -```bash -forge diagnose "" -``` - -## `forge imagine` - -परिणाम सिमुलेशन — किसी कार्य के लिए पूर्वानुमानित ब्रेक्स + न्यूनतम ड्राई-रन टेस्ट सूट। - -```bash -forge imagine "" -forge imagine "" --run # execute the minimal suite sandboxed -``` - -## `forge lean` - -स्कोप-न्यूनता (M5) — डिफ़ के पदचिह्न को उस बनाम मापें जो कार्य ने माँगा था। - -```bash -forge lean -``` - - - `route`, `impact`, `scope`, `context`, `anchor`, और `lean` चरण सभी `forge substrate` - के अंदर चलते हैं। जब आपको केवल एक ही संकेत चाहिए तो उन्हें अलग-अलग कॉल करें। - diff --git a/mintlify/hi/concepts/config-compiler.mdx b/mintlify/hi/concepts/config-compiler.mdx deleted file mode 100644 index ee9833b..0000000 --- a/mintlify/hi/concepts/config-compiler.mdx +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: "चार-परत कॉन्फ़िग कंपाइलर" -description: "सब्सट्रेट को एक बार लिखें; forge sync इसे प्रत्येक टूल के नेटिव कॉन्फ़िग में संकलित करता है। चार परतें बताती हैं कि दिमाग कैसे व्यक्त होता है; कंपाइलर बताता है कि यह कैसे डिलीवर होता है।" ---- - -आप सब्सट्रेट को एक बार लिखते हैं। `forge sync` उस स्रोत को प्रत्येक टूल के नेटिव कॉन्फ़िग में -संकलित करता है। चार परतें बताती हैं कि _दिमाग कैसे व्यक्त किया जाता है_; कंपाइलर बताता है -कि _यह कैसे डिलीवर होता है_। - -```mermaid -flowchart TD - S["source/ · rules.json · substrate.json · mcp.json"] -->|"forge sync — content-hash + DO-NOT-EDIT headers"| N["native configs · CLAUDE.md · AGENTS.md · .cursor · .gemini · .aider"] - S -. configures .-> L - subgraph L["the four layers"] - direction LR - T["tools · model-invoked skills"] - C["crew · isolated sub-agents"] - G["guards · deterministic hooks"] - M["mcp · atlas + substrate server"] - end -``` - -## एक स्रोत, कई एमिटर - -नियम **एक बार** लिखें (`source/rules.json`); एक डिटर्मिनिस्टिक कंपाइलर (`forge sync`) -प्रत्येक टूल के नेटिव फ़ॉर्मैट को कंटेंट-हैश हेडर के साथ एमिट करता है, जिससे ड्रिफ़्ट का -पता लगाया जा सकता है और पुनः चलाना no-op बन जाता है। कोई भी नियम कभी दो बार नहीं लिखा -जाता। कैनोनिकल स्रोत तीन फ़ाइलें हैं: - -| स्रोत फ़ाइल | इसमें क्या होता है | -| ----------------------- | -------------------------------------------------------------------- | -| `source/rules.json` | कैनोनिकल इंजीनियरिंग नियम (git, testing, security, style)। | -| `source/substrate.json` | Cognitive-substrate डिफ़ॉल्ट — थ्रेशोल्ड, रूटिंग, LLM नॉब्स। | -| `source/mcp.json` | MCP सर्वर परिभाषाएँ जो प्रत्येक टूल में एमिट होती हैं। | - -## चार परतें - -प्रत्येक परत ब्रांड-नामित है और क्रॉस-टूल एमिट होती है। - - - - `~/.forge/tools/` → `~/.claude/skills/`। मॉडल-इनवोक्ड स्किल्स, जो `SKILL.md` - मानक (`name` + `description` frontmatter) का पालन करती हैं। - - - `~/.forge/crew/` → `~/.claude/agents/`। पृथक-कॉन्टेक्स्ट सब-एजेंट जैसे कि scout, - verifier, और frontend-verifier। - - - `~/.forge/guards/` → `settings.json` हुक्स। **एकमात्र परत जो सुझाने के बजाय - _प्रवर्तन_ करती है।** एक guard एक डिटर्मिनिस्टिक हुक है जिससे मॉडल ड्रिफ़्ट नहीं कर - सकता। `CLAUDE.md` में प्रोज़ नियम स्वीकार किए जाते हैं और फिर कॉम्पैक्शन के बाद - भूल जाते हैं; एक guard ऐसा नहीं करता। हर प्रवर्तनीय invariant यहीं होना चाहिए। - - - Forge एक stdio सर्वर (`src/cortex_mcp.js`) शिप करता है जो 19 MCP टूल्स एक्सपोज़ - करता है: सब्सट्रेट चेक्स (`substrate_check` / `predict_impact` / - `assumption_gate` / …), मेमोरी रीड्स _और_ राइट्स (`forge_remember`, ledger - ratify/retract), और ops/health। - - - -क्रॉस-कटिंग चिंताएँ चारों में से गुज़रती हैं: **atlas** (कोड ग्राफ़), **lean** -(न्यूनतमवाद — एक टूल और एक Stop-guard दोनों के रूप में शिप होता है, ताकि यह लागू हो -चाहे मॉडल इसे इनवोक करे या नहीं), और **recall** (मेमोरी)। - -## प्रोज़ के ऊपर Guard - -जिन नियमों से मॉडल ड्रिफ़्ट कर सकता है वे प्रोज़ में रहते हैं; जिन्हें उसे **कभी नहीं** -तोड़ना चाहिए वे guards (डिटर्मिनिस्टिक शेल हुक्स) में रहते हैं। एक guard कॉन्टेक्स्ट -कॉम्पैक्शन के बाद भुलाया नहीं जा सकता। - - - हर प्रवर्तनीय invariant को `CLAUDE.md` से बाहर एक guard में ले जाएँ; प्रोज़ को पतला - रखें। Forge के डिज़ाइन में यह एकमात्र सबसे महत्वपूर्ण अनुशासन है। - - -## सत्यापित क्रॉस-टूल एमिट मैट्रिक्स - -Forge **नौ टूल्स** के लिए कॉन्फ़िग एमिट करता है, साथ ही Roo Code और VS Code के लिए एक -MCP सर्वर। प्रत्येक पंक्ति वेंडर डॉक्स के विरुद्ध पुष्टि की गई है। - -| टूल | नेटिव लक्ष्य | Forge कैसे एमिट करता है | -| ------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------- | -| **Claude Code** | `CLAUDE.md` (+ `.claude/rules/*.md`, `settings.json`) | पतला `CLAUDE.md` जिसकी पहली पंक्ति `@AGENTS.md` है; guards → settings | -| **Codex** | `AGENTS.md` नेटिव (32 KiB cap) | रूट पर कैनोनिकल `AGENTS.md` **ही** स्रोत है | -| **Cursor** | `AGENTS.md` + `.cursor/rules/*.mdc` | फ़्लैट नियमों के लिए `AGENTS.md`; स्कोपिंग आवश्यक होने पर `.mdc` | -| **Gemini** | `GEMINI.md`, या `context.fileName` opt-in के ज़रिए `AGENTS.md` | दूसरी कॉपी टालने के लिए `.gemini/settings.json` लिखता है | -| **Aider** | `.aider.conf.yml` में `read:` के ज़रिए `CONVENTIONS.md` | `read: AGENTS.md` के साथ `.aider.conf.yml` एमिट करता है | -| **Copilot** | रूट `AGENTS.md` + `.github/copilot-instructions.md` | रूट `AGENTS.md` पर निर्भर करता है; वैकल्पिक `.github` पॉइंटर | -| **Windsurf/Devin** | `AGENTS.md` ऑटो-डिस्कवर (caps 6k/12k chars) | caps के अंतर्गत रूट `AGENTS.md`; `.windsurf` बनाम `.devin` पहचानता है | -| **Zed** | प्रीसिडेंस सूची का पहला मैच जिसमें `AGENTS.md` शामिल है | `AGENTS.md` एमिट करता है; doctor किसी भी shadowing legacy फ़ाइल को फ़्लैग करता है | -| **Continue** | `.continue/rules/*.md` + `.continue/mcpServers/*.yaml` | एक नियम फ़ाइल और Forge MCP सर्वर कॉन्फ़िग एमिट करता है | - -Roo Code और VS Code को Forge MCP सर्वर `forge init` के ज़रिए मिलता है (`.roo/mcp.json`, -`.vscode/mcp.json`) न कि किसी नियम फ़ाइल के ज़रिए। - - - **Char caps वास्तविक हैं।** Codex 32 KiB पर, Windsurf 6k/12k पर ट्रंकेट करता है। - `forge sync` एक स्रोत आकार बजट लागू करता है ताकि कोई कॉन्फ़िग कभी चुपचाप ट्रंकेट न हो। - diff --git a/mintlify/hi/concepts/cross-session-memory.mdx b/mintlify/hi/concepts/cross-session-memory.mdx deleted file mode 100644 index c4446fa..0000000 --- a/mintlify/hi/concepts/cross-session-memory.mdx +++ /dev/null @@ -1,93 +0,0 @@ ---- -title: "क्रॉस-सेशन मेमोरी" -description: "सेशन एंकरिंग, कम्प्लीशन गेट, हैंडऑफ़ स्नैपशॉट, और डिसीज़न लॉग — वह परत जो सेशन एम्नेसिया और आंशिक कार्य को खत्म करती है।" ---- - -यह परत जिन दो विफलता मोड्स को खत्म करने के लिए है: **आंशिक कार्य** (कोड बदलाव उन artifacts -के बिना जो उस पर निर्भर हैं) और **सेशन एम्नेसिया** (अगला सेशन उस बात को फिर से मान लेता है -जो इस सेशन को पता थी)। निर्देश सही व्यवहार की _संभावना_ बढ़ाते हैं; डिटर्मिनिस्टिक हुक्स -एक _न्यूनतम स्तर_ की गारंटी देते हैं। - -## सेशन एंकरिंग - -`SessionStart` पर (`src/session.js`), Forge प्रति सेशन एक बार `HEAD` रिकॉर्ड करता है, -सप्ताह-पुराने सेशन artifacts को छाँटता है, और एक ताज़ा ओरिएंटेशन इंजेक्ट करता है: - - - - पिछले सुधारों से खनन किए गए Cortex पाठ। - - - घोषित लक्ष्य, ताकि ड्रिफ़्ट को उसके विरुद्ध मापा जा सके। - - - सीमित `.forge/state.md` जो पिछले सेशन ने लिखा था। - - - हाल के कमिट्स और uncommitted बदलाव — प्रमाण, प्राथमिकताएँ नहीं। - - - -एक ताज़ा सेशन प्राथमिकताओं पर नहीं, प्रमाण पर ओरिएंट होता है। - -## कम्प्लीशन गेट - -केवल एक Stop-path guard जवाब दे सकता है वह है `completion-gate.sh` -(`src/gate.js`)। यह सिंक्रोनसली चलता है; पाठ-खनन `cortex.sh stop` डिटैच्ड रहता है -और कभी ब्लॉक नहीं कर सकता। - -बदला हुआ सेट **सेशन-स्कोप्ड** है: उन कमिट्स की फ़ाइलें जिनका committer समय सेशन शुरू होने -पर या उसके बाद है, साथ ही working-tree बदलाव माइनस वह गंदगी जो `SessionStart` पर -स्नैपशॉट की गई थी — इसलिए पहले से मौजूद संपादन, ब्रांच स्विच, और `git pull` कभी एजेंट पर -नहीं थोपे जाते। - - - यदि कोड बदला और उसके साथ कोई doc या state artifact नहीं आया, तो gate **एक बार ब्लॉक करता है** - एक repair checklist को कारण के रूप में देते हुए। बाकी हर मामले में यह allow करता है, और - हर आंतरिक त्रुटि allow करती है (fail-open)। `FORGE_STOPGATE=0` इसे अक्षम करता है। - - -जिन सेशनों में code बदला है, उनके लिए gate **test evidence** भी माँगता है — या तो सेशन के -diff में एक test file, या मौजूदा बदलावों के विरुद्ध एक ताज़ा passing `forge verify`। -अकेला `forge handoff` snapshot अब code-change branch of the gate को clear नहीं करता। - -Repair checklist उन टूल्स की ओर इशारा करता है जो काम पूरा करते हैं: - -```bash -forge verify # record the test evidence for code changes -forge docs sync # sweep the diff for stale doc mentions -forge handoff "" --next "" # write the bounded session snapshot -forge decide " — " # record a choice so no session re-decides it -``` - -## हैंडऑफ़ और निर्णय - -दो स्टोर्स सेशनों में ज्ञान बनाए रखते हैं: - -| स्टोर | सिमैंटिक्स | -| ------------------- | ------------------------------------------------------------------------------------ | -| `.forge/state.md` | एक सीमित **rewrite** (स्नैपशॉट) — लोडर लागत हमेशा `O(bound)` रहती है। | -| `.forge/decisions.md` | Append-only **ADR-lite** (`D-####`) जिसके साथ एक machine-readable decision ledger twin है। | - -दोनों write पर secrets को अस्वीकार करते हैं। `state.md` हर सेशन शुरू होने पर पुनः इंजेक्ट होता है; -`decisions.md` को पहले पढ़ा जाता है, इससे पहले कि कुछ ऐसा फिर से तय किया जाए जो पिछले सेशन -ने तय किया था। - -```bash -forge handoff "" --next "" -forge decide " — " -forge decide # read the log before re-deciding -``` - -## Diff-आधारित docs sweep - -`forge docs sync` diff-आकार वाले प्रश्न का उत्तर देता है: बदले गए identifiers (paths, -definitions, और called symbols, जोड़ी गई _और_ हटाई गई लाइनों से) प्रत्येक doc artifact -के विरुद्ध swept → UPDATED / STALE (file:line hits के साथ) / VERIFIED-UNAFFECTED, कारण -रिकॉर्ड होने के साथ। यह एक शुद्ध रिपोर्टर है; कम्प्लीशन गेट दाँत प्रदान करता है। - - - `recall` और `cortex` केवल file-and-prompt मेमोरी हैं — **weight-level** learning **नहीं**। - Consolidation एक summarizer है जो hallucinate कर सकता है, इसलिए यह advisory, - मानव-समीक्षा-योग्य, और secret-free बना रहता है। - diff --git a/mintlify/hi/concepts/model-routing.mdx b/mintlify/hi/concepts/model-routing.mdx deleted file mode 100644 index 776f240..0000000 --- a/mintlify/hi/concepts/model-routing.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "मॉडल रूटिंग" -description: "एक डिटर्मिनिस्टिक, diffable रुब्रिक डिस्पैच से पहले सबसे सस्ता सक्षम मॉडल टियर चुनता है — self-hosted gateways के लिए एक fail-safe remap के साथ।" ---- - -Forge किसी कार्य के लिए सबसे सस्ते सक्षम मॉडल की सिफ़ारिश डिस्पैच से **पहले** करता है, एक -डिटर्मिनिस्टिक रुब्रिक से जिसे आप repo में पढ़ सकते हैं (`src/model_tiers.json`)। एक gateway -जो रिक्वेस्ट समय पर proxy के अंदर निर्णय लेता है, उसके विपरीत, रूटिंग निर्णय git में -दृश्यमान और diffable है। - -## एक टियर की सिफ़ारिश करें — `forge route` - -```bash -forge route "" # cheapest capable model tier for the task -forge route gateway # emit LiteLLM gateway config -``` - -सिफ़ारिश एक लेबल्ड बैंक (English + Hinglish rows) के ऊपर exemplar k-NN गणित है, जो -overlap-similarity मेट्रिक और एक confidence gate के तहत की जाती है — keyword lookup नहीं। - - - अनुशंसित `route.tier` पर शुरू करें और केवल एक बाहरी verifier के विफल होने के बाद escalate - करें, कभी preemptively नहीं। इससे जब कार्य को वास्तव में क्षमता की ज़रूरत होती है तब - क्षमता सीमित किए बिना खर्च कम रहता है। - - -## पहले Intent, फिर टियर - -रूटिंग अपनी गणित को intent detection (`src/intent.js`) के साथ साझा करती है: एक prompt -उसी exemplar k-NN estimator द्वारा एक intent में मैप होता है। ध्यान दें कि दोनों अलग-अलग -stop-sets का उपयोग करते हैं — route सामान्य verbs (`fix` / `add` / `build`) को complexity -noise मानती है, लेकिन वही verbs intent signal होते हैं। - -## टियर तालिका - -टियर तालिका (`src/model_tiers.json`) परिवार (haiku / sonnet / opus / fable) के अनुसार -सार्वजनिक Anthropic मॉडल IDs को पिन करती है। Doc कीमतें docs check द्वारा इस फ़ाइल के -विरुद्ध reconciled होती हैं, इसलिए prose और तालिका ड्रिफ़्ट नहीं कर सकते। - -## Self-hosted gateway remap - -एक self-hosted LiteLLM या proxy gateway अपने खुद के मॉडल नाम देता है, इसलिए एक stock ID -सीधे भेजने पर 404 आएगा। जब एक non-default gateway base URL कॉन्फ़िगर होता है, तो Forge -(`src/gateway_model_map.js`) `GET /v1/models` को **प्रति process एक बार** fetch करता है -और प्रत्येक विज्ञापित id को हर टियर के family के विरुद्ध score करता है: - - - - Family शब्द (haiku / sonnet / opus / fable) मैच होना चाहिए — यह एक hard gate है। - - - Family के भीतर, टियर के नाम टोकनों का `setOverlap` गुणांक सर्वश्रेष्ठ मैच चुनता है। - - - Ties canonical नाम के सबसे करीब id की ओर टूटते हैं। - - - - - Remap gateway से **केवल** तब परामर्श करता है जब resolved id एक _stock_ ID हो — एक स्पष्ट - `.forge/providers.json` alias या एक `ANTHROPIC_MODEL` override को कभी नहीं छुआ जाता। यह - no gateway, unreachable `/v1/models`, या no family match पर stock ID पर fail-safe रहता है, - ताकि सीधे `api.anthropic.com` उपयोगकर्ता byte-identical रहें। - - -`forge doctor` की **gateway models** पंक्ति सत्यापन के लिए resolved `tier → model` मैपिंग -प्रिंट करती है। - -## Providers और लागत - -```bash -forge config # show / switch / add providers, set the default model -forge cost # real per-day spend -forge cost --stages # measured per-stage cost factors -``` - - - `forge cost --stages` **केवल मापे गए stages** रिपोर्ट करता है — बिना events वाला stage - "no data" कहता है, कभी default नहीं। एक संख्या तब तक धारणा है जब तक मापी न जाए। - diff --git a/mintlify/hi/concepts/pre-action-gate.mdx b/mintlify/hi/concepts/pre-action-gate.mdx deleted file mode 100644 index abe3341..0000000 --- a/mintlify/hi/concepts/pre-action-gate.mdx +++ /dev/null @@ -1,100 +0,0 @@ ---- -title: "प्री-एक्शन गेट" -description: "forge substrate मॉडल के कोड संपादित करने से पहले एक क्रमबद्ध चेक पास चलाता है और एक ही verdict देता है — assumptions, routing, impact, scope, memory, और verification।" ---- - -**Cognitive substrate** — वह परत जो मॉडल के कोड संपादित करने से _पहले_ चलती है। `forge -substrate ""` (और MCP टूल `substrate_check`) एक क्रमबद्ध पास चलाता है और एक ही -verdict देता है। यह अलग-अलग कॉल किए जा सकने वाले चरणों — `preflight`, `route`, `atlas`, -`impact`, `reuse`, `context`, `scope`, `lean`, `anchor`, `verify` — को एक pre-action -अनुबंध में मिलाता है। - -```mermaid -flowchart TD - RE["referenced entities"] --> INTAKE - subgraph INTAKE["intake"] - direction LR - PF["preflight · assumption gap"] --> RT["route · cheapest tier"] - end - INTAKE --> ANALYSIS - subgraph ANALYSIS["analysis"] - direction LR - AT["atlas · code graph"] --> IM["impact · blast radius"] --> PT["predict · failing tests"] --> RU["reuse · cache hit?"] - end - ANALYSIS --> SAFETY - subgraph SAFETY["safety + fit"] - direction LR - CX["context · completeness gate"] --> SC["scope · coupled files"] --> ME["memory · recall + lessons"] --> MN["minimality · lean footprint"] --> GA["goal-anchor · drift check"] - end - SAFETY --> VD["verdict"] -``` - -## तीन चरण - - - - **preflight** assumption gap ढूँढ़ता है — कार्य क्या नाम लेता है जिसे repo परिभाषित - नहीं करता। **route** सबसे सस्ता सक्षम मॉडल टियर चुनता है। - - - **atlas** कोड ग्राफ़ पढ़ता है, **impact** blast radius की गणना करता है, **predict** - उन tests के नाम बताता है जिनके विफल होने की संभावना है, और **reuse** एक सत्यापित - cache hit की जाँच करता है। - - - **context** completeness gate चलाता है, **scope** coupled फ़ाइलें सामने लाता है, - **memory** recall + lessons इंजेक्ट करता है, **minimality** lean footprint मापता है, - और **goal-anchor** drift की जाँच करता है। - - - -## Blast radius - -**Blast radius** — फ़ाइलों का वह सेट जिस पर एक edit के प्रभाव की भविष्यवाणी की जाती है, -कोड ग्राफ़ से पढ़ा गया। `forge impact` इसकी गणना करता है; पाइपलाइन मॉडल के कुछ छूने से -पहले इसे सामने लाती है। - -```bash -forge impact verifyToken # predicted impacted files for a symbol -forge impact src/auth.js # …or for a file -``` - -## डिफ़ॉल्ट रूप से Advisory - -Verdict **डिफ़ॉल्ट रूप से advisory** है — यह रिपोर्ट करता है, ब्लॉक नहीं करता। सबसे मज़बूत -संकेतों को hard block में बदलने के लिए `FORGE_ENFORCE=1` सेट करें: - - - - preflight को कोई actionable intent नहीं मिलता — एक underspecified task। - - - completeness gate predicted edit set को cover नहीं कर सकता। - - - impacted set डिफ़ॉल्ट ~25-file threshold से अधिक है। - - - -बाकी सब कुछ एक warning बनी रहती है जिसे मानव override कर सकता है। - - - Claude Code पर पूरा गेट **हर prompt पर स्वचालित रूप से** एक `UserPromptSubmit` hook के - ज़रिए चलता है — clean tasks पर silent। `forge substrate "" --json` - scripting के लिए machine-readable verdict देता है। - - -## इसे चलाना - -```bash -forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" -forge substrate "" --json -``` - -यदि verdict `ASK FIRST` है, तो संपादित करने से पहले लौटाए गए `assumption.questions` -पूछें — एक under-specified task का अनुमान न लगाएँ। अनुशंसित `route.tier` पर शुरू करें और -केवल एक बाहरी verifier के विफल होने के बाद escalate करें, कभी preemptively नहीं। - - - मेमोरी stage proof-carrying ledger से पढ़ता है। - diff --git a/mintlify/hi/concepts/proof-carrying-memory.mdx b/mintlify/hi/concepts/proof-carrying-memory.mdx deleted file mode 100644 index 741dc07..0000000 --- a/mintlify/hi/concepts/proof-carrying-memory.mdx +++ /dev/null @@ -1,115 +0,0 @@ ---- -title: "Proof-carrying memory" -description: "प्रत्येक संग्रहीत तथ्य, पाठ, या reuse artifact एक claim है जो अपने साथ अपना प्रमाण रखता है — जिस पर तभी भरोसा किया जाता है जब स्वतंत्र oracles उसका confidence एक floor से ऊपर उठा दें।" ---- - -**Proof-carrying memory (PCM)** — प्रत्येक संग्रहीत तथ्य, पाठ, या reuse artifact एक -_claim_ है जो अपने साथ अपना प्रमाण रखता है। इस पर तभी भरोसा किया जाता है जब स्वतंत्र -oracles (tests, CI, एक मानव accept/revert) इसका confidence एक floor से ऊपर उठा दें। -एक ग़लत पाठ ossify होने के बजाय decay होकर बाहर हो जाता है। - - - "Proof-carrying memory" हमारा नाम है **evidence-referenced, content-addressed - memory** के लिए — एक claim जिसे उसके content के hash द्वारा address किया जाता है और - उसे उन oracle outcomes से जोड़ा जाता है जो उसका समर्थन करते हैं। "Proof" वह evidence - trail और confidence नियम है, **किसी formal machine-checked proof के तौर पर नहीं**; loop - में कोई theorem prover नहीं है। - - -## एक store, कई writers - -सभी memory subsystems एक ही store पर converge होते हैं। `recall`, `remember`/`brain`, -`cortex` lessons, `reuse` artifacts, और doom-loop `diagnose` results सभी -content-addressed claims को `.forge/ledger/` में लिखते हैं। - -```mermaid -flowchart LR - subgraph EV["local events"] - direction TB - E1["recall / remember"] - E2["cortex lesson"] - E3["reuse mint"] - E4["diagnose"] - end - EV -->|"content-addressed claims"| LG["(.forge/ledger)"] - O["independent oracles · tests · CI · human accept/revert"] -->|"append evidence · move confidence"| LG - TM["teammate ledgers"] <-->|"git union-merge · conflict-free"| LG - LG --> RV["merged read view · recall list · lesson inject · brain index"] -``` - -## यह conflicts के बिना क्यों converge होता है - -क्योंकि एक claim के bytes `(kind, body, scope)` का शुद्ध function हैं, हर replica एक ही -identity कंप्यूट करता है — इसलिए teammate ledgers plain git पर बिना conflicts के आपस -में fold हो जाते हैं। - -यांत्रिक रूप से: - -- **Evidence और tombstones append-only**, hash-deduped logs हैं। -- **Confidence (`val`)** एक decayed Beta posterior है, जिसे केवल oracles ही हिलाते हैं। -- **Merge एक join-semilattice है** — property-tested कि यह commutative, associative, - और idempotent है — इसलिए ledgers किसी भी क्रम में converge हो जाते हैं। - - - `forge init` union-merge `.gitattributes` नियम emit करता है जो ledger को चाहिए; - `forge ledger merge ` किसी अन्य ledger tree को fold कर लेता है। पूरा निर्णय - ADR-0006 (proof-carrying memory) में दर्ज है। - - -## Oracles ही confidence हिलाते हैं — कुछ और नहीं - -केवल स्वतंत्र oracles एक memory का confidence हिला सकते हैं: - - - - एक passing test जो claim को exercise करता है, उसका confidence बढ़ाता है। - - - एक green pipeline स्वतंत्र evidence है कि claim अभी भी टिकी हुई है। - - - एक explicit accept या एक revert सबसे मज़बूत signal है। - - - -Unverifiable evidence को एक closed `ORACLES` table (`src/ledger.js`) द्वारा अस्वीकार -कर दिया जाता है। असमीक्षित knowledge deletion की ओर नहीं, _uncertainty_ की ओर decay -होता है — निष्क्रिय claims audit के लिए रखे जाते हैं, कभी चुपचाप हटाए नहीं जाते। - -## Ledger surface - -```bash -forge ledger stats # what the repo knows, by kind and trust level -forge ledger verify # re-check claims are in normal form -forge ledger show # a claim and its evidence trail -forge ledger blame # who minted it, every oracle outcome, per-author trust -forge ledger query "" # retrieve claims by relevance -forge ledger ratify # human accept -forge ledger retract # tombstone a claim -forge ledger merge # fold a teammate's ledger in, conflict-free -forge ledger import # bridge legacy stores into the ledger -``` - -Per-user ledger के लिए `--personal` जोड़ें। - -## Reuse cache भी proof-carrying है - -`forge reuse` एक proof-carrying code cache है। एक generated artifact तभी दोबारा serve -होता है जब उसका evidence अभी भी टिका हो — confidence floor से ऊपर हो **और** उसके atlas -dependencies अभी भी resolve हों। अन्यथा यह generation पर fall through करता है और वापसी -पर एक fresh claim mint करता है। - -```mermaid -flowchart LR - SP["spec"] --> FP["fingerprint · MinHash + LSH"] - FP --> LD["match ladder · exact to near to adapt to miss"] - LD --> GT{"confidence >= floor AND deps resolve?"} - GT -->|"yes"| SV["serve · proof holds"] - GT -->|"miss"| GN["generate"] - GN -->|"mint claim"| MT["(.forge/ledger)"] -``` - - - MinHash near-match बहुत छोटे specs पर कमज़ोर है। एक वैकल्पिक embeddings backend - (`FORGE_EMBED`) इसे बेहतर बनाता है; MinHash zero-dependency डिफ़ॉल्ट बना रहता है। - diff --git a/mintlify/hi/concepts/verification-gates.mdx b/mintlify/hi/concepts/verification-gates.mdx deleted file mode 100644 index 6b69944..0000000 --- a/mintlify/hi/concepts/verification-gates.mdx +++ /dev/null @@ -1,137 +0,0 @@ ---- -title: "Verification gates" -description: "स्वतंत्र सत्यापन, hallucinated-symbol flag, spec-as-contract, और skill-gate — ऐसे चेक्स जिन्हें आप चला सकते हैं जो सटीकता को घटाते हैं, पर कभी प्रमाणित नहीं करते।" ---- - -कोई भी काम तब तक "पूरा" नहीं है जब तक आप एक ऐसा चेक न चला सकें — एक test, एक build exit -code, एक screenshot। Forge के verification gates प्रत्येक एक और catch जोड़ते हैं। -प्रति-task miss rate `1 − p` और gate catch rate `c` के साथ, silent misses `(1 − p)(1 − c)` -तक गिर जाते हैं, और यहाँ हर gate एक और `c` है। - - - **Verification घटाता है, प्रमाणित नहीं करता।** Crew verifiers और hallucinated-symbol - flag review burden कम करते हैं; वे कोड को सही साबित नहीं करते। Tests और मानव सुधार - हमेशा जीतते हैं। - - -## स्वतंत्र सत्यापन — `forge verify` - -एक स्वतंत्र gate: यह repo के वास्तविक tests चलाता है, hallucinated symbols flag करता है, और -provenance जाँचता है। - -```bash -forge verify # tests + hallucinated-symbol + provenance -forge verify --deep # multi-lens consensus — several independent checks must agree -``` - - - `--deep` एक multi-lens consensus तक escalate करता है: बदलाव को कई स्वतंत्र - verification lenses से गुज़रना पड़ता है, केवल एक से नहीं। - - -`forge verify --deep` एक binary pass/fail के बजाय एक चार-अवस्था वाला `status` रिपोर्ट करता है: - -- `PASS` — हर lens सहमत हुआ **और** core `forge verify` tests status भी `PASS` है। केवल - यही state verified मानी जाती है। -- `FAIL` — कम-से-कम एक lens ने वास्तविक failure रिपोर्ट किया। -- `INCOMPLETE` — कोई lens पूरा नहीं हो सका (timeout, crash, missing dependency)। कुछ भी - disprove नहीं हुआ, पर कुछ prove भी नहीं हुआ। -- `NOT_CONFIGURED` — इस repo के लिए कोई lenses wired नहीं हैं, इसलिए `--deep` के पास - check करने को कुछ नहीं था। - -`PASS`-implies-base-`PASS` नियम जानबूझकर है: एक हरा deep consensus कभी भी एक लाल base run -से आगे नहीं निकल सकता, इसलिए base test lens पर `INCOMPLETE` या `NOT_CONFIGURED` deep -result को उसी के अनुरूप downgrade कर देता है। - -## Hallucinated-symbol flag — `forge atlas has` - -`forge atlas has ` hallucination check है: यदि मॉडल किसी ऐसे symbol को call -करता है जो code graph में नहीं है, तो gate उसे flag करता है। - -```bash -forge atlas build # index this repo's symbols → .forge/atlas.json -forge atlas has useAuth # "not found" = likely hallucinated -``` - -Atlas जानबूझकर plain JSON है — Codex, Cursor, Gemini, और Aider `.forge/atlas.json` -को CLI या plain `jq` के ज़रिए पढ़ते हैं, बिना किसी MCP dependency के। - -## Spec-as-contract — `forge spec` - -व्यवहार को एक spec से pin करें और उससे drift पहचानें: - -```bash -forge spec init # scaffold an OpenSpec contract -forge spec lock # lock the current spec as the contract -forge spec check # report drift against the locked contract -``` - -## Skill-gate — `forge scan` - -किसी skill या MCP server को install करने से पहले, उसे injection, RCE, या exfiltration -के लिए जाँचें: - -```bash -forge scan -``` - - - Clean scan **safety certification नहीं है।** Built-in heuristic केवल known attack - shapes (critical) और कुछ high-severity patterns को पकड़ता है; pass का मतलब है _"कोई - critical signature नहीं मिला"_, _"install करने के लिए सुरक्षित"_ नहीं। हमेशा source, - permissions, package provenance, और network behaviour ख़ुद review करें। एक - **high**-severity finding को safe के रूप में मार्क नहीं किया जाता, भले ही यह hard-block - न करे। External scanner opt-in है और जब तक आप उसे enable न करें, कोई network call - नहीं करता। - - -## Hardening — `forge harden` - -Secrets और unsafe changes को बाहर रखने वाले security controls को wire करें: - -```bash -forge harden # gitleaks pre-commit + sandbox settings -``` - -## Commit-level gate — `forge precommit` - - - `forge precommit` एक commit-level gate है — यह commit time पर verification - floor चलाता है ताकि आंशिक या unverified काम land होने से पहले पकड़ा जाए। - - -## Completion gate — test evidence अनिवार्य - -Stop-path completion gate (देखें -[क्रॉस-सेशन मेमोरी](/hi/concepts/cross-session-memory)) अब एजेंट के handoff को इस बात के -प्रमाण के रूप में स्वीकार नहीं करता कि code changes पूरे हो चुके हैं। किसी भी ऐसे सेशन के लिए -जिसने source code को छुआ है, gate **वास्तविक test evidence** माँगता है: - -- सेशन के diff में बदली गई एक test file, **या** -- मौजूदा बदलावों के विरुद्ध रिकॉर्ड किया गया एक ताज़ा passing `forge verify`। - -अकेला `forge handoff` snapshot gate को संतुष्ट नहीं करता — यह intent रिकॉर्ड करता है, -verification नहीं। यदि दोनों में से कोई भी प्रमाण मौजूद नहीं है, तो gate एक बार एक repair -checklist के साथ ब्लॉक करता है: - -```bash -forge verify # produce the test evidence -forge handoff "" --next "" # then snapshot the session -``` - -Doc-only, config-only, और अन्य non-code सेशन प्रभावित नहीं होते — test-evidence अनिवार्यता -केवल तभी लागू होती है जब सेशन का diff वास्तव में code बदलता है। - -## UI checks — `forge uicheck` - -Deterministic UI checks, पहले तीन lenses के लिए कोई LLM नहीं और कोई screenshots नहीं: - -```bash -forge uicheck contrast # WCAG contrast ratio -forge uicheck fingerprint # deterministic design fingerprint -forge uicheck design # slop-distance + conformance gate -forge uicheck visual # Playwright-rendered check (opt-in tier) -``` - -इसे `forge taste` के साथ जोड़ें ताकि एक visual direction चुनें (brutalist, corporate, -editorial, minimalist, playful) और `design` gate की thresholds को parameterize करें। diff --git a/mintlify/hi/guides/radar-deps.mdx b/mintlify/hi/guides/radar-deps.mdx deleted file mode 100644 index b18f621..0000000 --- a/mintlify/hi/guides/radar-deps.mdx +++ /dev/null @@ -1,69 +0,0 @@ ---- -title: "radar के साथ dependencies को current रखना" -description: "forge radar आपकी dependencies को currency rings में समूहित करता है ताकि stale या drifting dependencies तंग करने से पहले सामने आ जाएँ।" ---- - - - `forge radar` उपलब्ध है। यह गाइड बताता है कि यह मौजूदा dependency-currency - discipline में कैसे फ़िट होता है; अपने installed version में उपलब्धता की पुष्टि करने के लिए - `forge --help` चलाएँ। - - -Forge के इंजीनियरिंग नियमों में से एक है: _dependency जोड़ने से पहले, live sources से -वर्तमान सर्वोत्तम विकल्प की पुष्टि करें, और वही पसंद करें जो प्रोजेक्ट पहले से उपयोग कर रहा है।_ -`forge radar` आपकी dependencies की standing state दिखाता है ताकि उस नियम के पीछे data हो। - -## विचार: currency rings - -`forge radar` प्रोजेक्ट की dependencies को concentric **currency rings** में समूहित करता है -इस आधार पर कि प्रत्येक कितना current है — केंद्र में up-to-date से लेकर किनारे पर stale -या drifting तक। Rings पढ़ना "हमने क्या drift होने दिया है?" का उत्तर देने का तेज़ तरीका है, -बिना हर package को हाथ से audit किए। - -```bash -forge radar -``` - -## Dependency सूची कहाँ से आती है - -Radar उसी manifest reading पर बनता है जो `forge stack` को शक्ति देती है, जो repo की -वास्तविक stack को उसके dependency manifests से पहचानती है: - -```bash -forge stack # languages, frameworks, package managers, real test commands -``` - -क्योंकि detection data-driven और ecosystems (`package.json`, `pyproject.toml`, `go.mod`, -`Cargo.toml`, `Gemfile`, `composer.json`, `pom.xml` / `build.gradle`, `*.csproj`) के -पार fail-safe है, radar उन्हीं manifests के set के लिए currency के बारे में तर्क कर सकता -है जिन्हें `stack` समझता है। - -## Loop में इसका उपयोग - - - - यह देखने के लिए `forge radar` चलाएँ कि कौन-सी dependencies पहले से drift हो रही हैं, - इससे पहले कि आप कोई जोड़ें या bump करें। - - - यदि कोई सक्षम, current dependency पहले से एक inner ring में है, तो नई जोड़ने के - बजाय उसका reuse करें — सबसे छोटा बदलाव जो फ़िट होता है, जीतता है। - - - जब आप किसी dependency को bump या replace करें, तो कारण दर्ज करें: - ```bash - forge decide "bump to — " - ``` - ताकि भविष्य का सेशन इस choice को दोबारा litigate करने के बजाय पढ़े। - - - - - Radar currency रिपोर्ट करता है; आपके लिए upgrade नहीं करता। इसके rings को एक मानव - निर्णय के लिए advisory input की तरह मानें — और किसी भी bump की repo के वास्तविक tests - (`forge verify`) के साथ पुष्टि करें, तभी उसे done कहें। - - - - Dependency bump के बाद, Quality gates चलाएँ — `forge verify` और `forge precommit`। - diff --git a/mintlify/hi/guides/team-memory.mdx b/mintlify/hi/guides/team-memory.mdx deleted file mode 100644 index ee2676b..0000000 --- a/mintlify/hi/guides/team-memory.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "Ledger के साथ टीम मेमोरी" -description: "किसी टीममेट के ledger को plain git पर, conflict-free, fold करें — कोई server नहीं, कोई sync service नहीं, बस files जो किसी भी क्रम में converge होती हैं।" ---- - -Substrate जो कुछ भी सीखता है — cortex lessons, `forge remember` facts, verified reuse -artifacts — वह content-addressed claims के रूप में एक git-native ledger -(`.forge/ledger/`) में land होता है, जो बिना conflicts के merge करने के लिए बनाया गया -है। कोई server नहीं और कोई sync service नहीं; यह बस git में files हैं। - -## तीन commands में team memory - - - - ```bash - forge init - ``` - अन्य बातों के साथ यह `.gitattributes` union-merge नियम emit करता है जो ledger को चाहिए। - - - Cortex lessons और `forge remember` facts आपके काम करते-करते claims को ledger में - shadow करते हैं — अलग से कुछ चलाने की ज़रूरत नहीं। - - - ```bash - git pull && forge ledger merge - ``` - किसी भी क्रम में — merge conflict-free है। - - - -## यह conflict क्यों नहीं कर सकता - -एक claim के bytes `(kind, body, scope)` का शुद्ध function हैं, इसलिए हर replica एक ही -knowledge के लिए एक ही identity कंप्यूट करता है। Merge एक join-semilattice है — -property-tested कि यह commutative, associative, और idempotent है — इसलिए दो टीममेट्स -के ledgers उसी state पर converge होते हैं, चाहे पहले कौन sync करे। - -```mermaid -flowchart LR - A["your ledger"] <-->|"git union-merge · conflict-free"| B["teammate ledger"] - A --> M["merged read view"] - B --> M - M --> R["recall list · lesson inject · brain index"] -``` - - - स्वतंत्र रूप से mint की गई identical knowledge **एक** claim पर converge होती है, जिसकी - provenance में हर author संरक्षित रहता है। - - -## Trust और provenance - -Confidence केवल स्वतंत्र oracles द्वारा हिलाया जाता है — tests, CI, एक मानव accept/revert — -इसलिए किसी टीममेट के ledger को import करना उनके नोट्स पर आँख मूँदकर भरोसा नहीं करता; यह -उनका _evidence_ import करता है। - -```bash -forge ledger blame # who minted a claim, every oracle outcome, per-author trust -forge ledger stats # the merged view, by kind and trust level -forge ledger verify # confirm every claim is in normal form -``` - -## टीम में Reuse - -एक बार किसी टीममेट का verified कोड merged ledger में आ जाए, तो आप उसे उसके proof के साथ -reuse कर सकते हैं: - -```bash -forge reuse query "" -``` - -एक hit working, test-confirmed कोड की ओर इशारा करता है और `forge ledger blame` जो उसे -साबित करता है — इसे regenerate करने के बजाय reuse करें। - - - निष्क्रिय claims audit के लिए रखे जाते हैं, कभी हटाए नहीं जाते; असमीक्षित knowledge - deletion की ओर नहीं, _uncertainty_ की ओर decay होती है। Ledger एक evidence trail है, - कोई cache नहीं जिसे आप चुपचाप खो सकें। - diff --git a/mintlify/hi/guides/zero-config-onboarding.mdx b/mintlify/hi/guides/zero-config-onboarding.mdx deleted file mode 100644 index e4597a6..0000000 --- a/mintlify/hi/guides/zero-config-onboarding.mdx +++ /dev/null @@ -1,88 +0,0 @@ ---- -title: "मार्गदर्शित, कम-कॉन्फ़िगरेशन Onboarding" -description: "पाँच मिनट में उत्पादक: एक बार install करें, एक repo को एक बार configure करें, एक task करें, और दूसरे दिन ledger का फ़ायदा मिलना शुरू करें — मार्गदर्शित, कम-कॉन्फ़िगरेशन, zero-touch नहीं।" ---- - -Forge का लक्ष्य है **मार्गदर्शित, कम-कॉन्फ़िगरेशन onboarding** — एक नया repo आमतौर पर लगभग -पाँच मिनट में उत्पादक हो जाता है। एक बार install करें, एक repo को एक बार configure करें, -एक task करें, और दूसरे दिन ledger का फ़ायदा मिलना शुरू हो जाता है। (यह low-configuration -है, zero-configuration नहीं: आप अभी भी CLI install करते हैं, हर repo में `forge init` -चलाते हैं, और कुछ paths Bash, Git, और `jq` मानते हैं।) - -```mermaid -flowchart TD - I["forge init"] --> Cfg["every tool configured from one source"] - Cfg --> Work["you work as usual"] - Work --> Gate["substrate checks each task · ask first? · which model? · what breaks?"] - Gate --> Edit["agent edits, with guardrails"] - Edit --> Learn["cortex learns from corrections"] - Learn -.->|next task is smarter| Work -``` - -## 1. Install (एक बार) - -अनुशंसित paths को किसी token या clone की ज़रूरत नहीं: - - - -```bash Plugin -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit -``` - -```bash CLI -npm install -g @codewithjuber/forgekit -``` - - - -```bash -forge doctor # everything green? -``` - -## 2. एक repo configure करें (प्रति repo एक बार) - -```bash -cd ~/your-project -forge init # emits AGENTS.md, CLAUDE.md, .gemini/settings.json, .aider.conf.yml … -``` - -अब Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed, और Continue सभी -**एक ही** नियम पढ़ते हैं — हर एक अपनी native फ़ाइल से। बाद में एक नियम बदलने के लिए -`source/rules.json` संपादित करें (या प्रति-repo `.forge/rules.json` छोड़ें), फिर -`forge sync` चलाएँ। - -## 3. Cognitive substrate का उपयोग करें - -```bash -forge substrate "" # ask/route/impact/scope/reuse/context/memory/verify in one pass -forge substrate "" --json -forge impact # the blast radius on its own -``` - -यदि `forge substrate` कहता है `ASK FIRST`, तो संपादित करने से पहले लौटाए गए प्रश्न पूछें। - -## 4. Extras का उपयोग करें - -```bash -forge atlas build # index this repo's symbols → .forge/atlas.json -forge atlas query useAuth # where is it defined? -forge atlas has useAuth # does it exist? "not found" = likely hallucinated -forge recall add "db port" "Postgres is on 5433 here, not 5432" -forge catalog # the Start-Here index of everything -``` - -## 5. दूसरा दिन: ledger सीख रहा है - -पहले दिन substrate ने जो कुछ भी सीखा — cortex lessons, remembered facts, verified -code — वह `.forge/ledger/` में claims के रूप में land हुआ। - -```bash -forge ledger stats # what the repo knows, by kind and trust level -forge ledger blame # who minted a claim, every oracle outcome -forge reuse query "" # verified code you already have -``` - - - आगे: किसी टीममेट के ledger को plain git पर, conflict-free, fold करें। - diff --git a/mintlify/hi/installation.mdx b/mintlify/hi/installation.mdx deleted file mode 100644 index 11a897c..0000000 --- a/mintlify/hi/installation.mdx +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: "इंस्टॉलेशन" -description: "एक ही पेड़ पर तीन प्रवेश द्वार: प्लगइन मार्केटप्लेस, npm ग्लोबल, और बिना-रजिस्ट्री github: install — साथ ही कंट्रिब्यूटर symlink सेटअप।" ---- - -Forge एक **एक पेड़, तीन प्रवेश द्वार** डिज़ाइन का पालन करता है: प्लगइन मैनिफ़ेस्ट, -हार्डन्ड इंस्टॉलर, और npm bin सभी उसी `global/` + `source/` पेड़ को संदर्भित करते हैं। -वह चैनल चुनें जो आपके टूल पर सूट करे। - -## एक चैनल चुनें - - - - Claude Code और Codex के लिए। गार्ड्स स्वतः वायर हो जाते हैं; मर्ज करने के लिए कुछ नहीं। - - - किसी भी टूल के लिए। सार्वजनिक npm रजिस्ट्री से `forge` CLI। - - - कोई रजिस्ट्री ज़रूरी नहीं — सीधे रेपो से इंस्टॉल करें। - - - क्लोन करें + `npm link`, या symlink सेटअप के लिए `bash install.sh`। - - - -## आवश्यकताएँ - -- **Node.js >= 20** -- **शून्य रनटाइम निर्भरताएँ** — सब कुछ Node बिल्ट-इन है। वैकल्पिक स्तर - (`FORGE_EMBED` एम्बेडिंग्स, `uicheck visual` के लिए Playwright) ऑप्ट-इन हैं और - कोई आवश्यक निर्भरता नहीं जोड़ते। - -## प्लगइन मार्केटप्लेस - -Claude Code और Codex के लिए अनुशंसित पथ जिसे न किसी टोकन की ज़रूरत है, न क्लोन की: - -```bash -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit -``` - -प्लगइन गार्ड्स को `${CLAUDE_PROJECT_DIR}` के माध्यम से वायर करता है ताकि प्री-एक्शन गेट -और कंप्लीशन गेट परिवेश में चलें। - -## npm ग्लोबल - -किसी भी टूल के लिए, सार्वजनिक npm से: - -```bash -npm install -g @codewithjuber/forgekit -forge doctor # everything green? -``` - -## बिना-रजिस्ट्री github: install - -```bash -npm install -g github:CodeWithJuber/forgekit -``` - -## कंट्रिब्यूटर / लोकल dev - - - -```bash npm link -git clone https://github.com/CodeWithJuber/forgekit.git -cd forgekit -npm link -``` - -```bash install.sh (symlink setup) -git clone https://github.com/CodeWithJuber/forgekit.git -cd forgekit -bash install.sh -``` - - - -इंस्टॉलर हार्डन्ड है: idempotent, symlink-आधारित, बैकअप के साथ, और कोई `curl | sh` नहीं। - -## सत्यापित करें - -आपने जो भी चैनल इस्तेमाल किया हो, इंस्टॉल की पुष्टि करें: - -```bash -forge doctor # tools, guards, MCP auth, config drift, update status -``` - - - `forge doctor` git चेकआउट्स के लिए एक ग़ैर-परेशान करने वाली "commits behind upstream" - सूचना भी दिखाता है। इसे शांत करने के लिए `FORGE_NO_UPDATE_CHECK=1` सेट करें। - हर पथ fail-open है — ऑफ़लाइन या detached HEAD "unknown" रिपोर्ट करता है, कभी error नहीं। - - -## Forge को अद्यतन रखना - -```bash -forge update --check # report whether a newer version is available -forge update # apply the update (git checkout or npm/copy install) -forge update --to # pin or downgrade to a specific version -``` - - - `forge init` चलाने और अपना पहला सब्सट्रेट चेक करने के लिए क्विकस्टार्ट पर जाएँ। - diff --git a/mintlify/hi/introduction.mdx b/mintlify/hi/introduction.mdx deleted file mode 100644 index 78fff95..0000000 --- a/mintlify/hi/introduction.mdx +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: "Forge: AI कोडिंग एजेंट्स के लिए संज्ञानात्मक सब्सट्रेट" -description: "Forge वह संज्ञानात्मक सब्सट्रेट है जो हर स्टेटलेस मॉडल में गायब है — मेमोरी, दूरदर्शिता और गार्डरेल्स — जो हर AI कोडिंग एजेंट को नेटिव कॉन्फ़िग के रूप में मिलता है।" ---- - -**हर AI कोडिंग एजेंट के लिए एक ही मस्तिष्क।** एक बड़ा भाषा मॉडल स्टेटलेस होता है: एक -कॉन्टेक्स्ट विंडो, जो हर कॉल पर मिटा दी जाती है। उसके पास आपकी टीम ने जो सीखा उसकी -कोई मेमोरी नहीं है, किसी एडिट से क्या टूटेगा इसका कोई पूर्वाभास नहीं है, और कोई -प्रवर्तित गार्डरेल्स नहीं हैं। Forge (`@codewithjuber/forgekit`) वही **संज्ञानात्मक -सब्सट्रेट** है — वह परत जो मॉडल द्वारा कोड एडिट करने से _पहले_ चलती है, और साक्ष्य-संदर्भित, -कंटेंट-एड्रेस्ड मेमोरी (जिसे हम "प्रूफ-कैरीइंग मेमोरी" कहते हैं), ह्यूरिस्टिक प्रभाव-पूर्वाभास, -और प्रवर्तित गार्डरेल्स प्रदान करती है — और एक **क्रॉस-टूल कॉन्फ़िग कंपाइलर** जो -उस मस्तिष्क को एक ही बार में हर टूल में नेटिव कॉन्फ़िग के रूप में पहुँचाता है। Claude Code -सबसे गहराई से परखा गया इंटीग्रेशन है; बाकी टूल्स को नेटिव कॉन्फ़िग और MCP टूल्स -मिलते हैं जिनका वास्तविक अभ्यास कम है। - - - - प्रूफ-कैरीइंग मेमोरी जो सत्रों और टीम-साथियों के बीच बनी रहती है। हर सबक, - तथ्य, और सत्यापित पुनरुपयोग एक ऐसा दावा है जो अपना साक्ष्य स्वयं वहन करता है। - - - किसी एडिट की ब्लास्ट रेडियस — कोड ग्राफ़ से पढ़ी गई उन फ़ाइलों का समूह जिन पर - प्रभाव पड़ने की भविष्यवाणी है, उन युग्मित फ़ाइलों सहित जिनका नाम आपने नहीं लिया। - - - डिटरमिनिस्टिक हुक उन नियमों को लागू करते हैं जिन्हें मॉडल कभी नहीं तोड़ सकता। - वे एक कॉन्टेक्स्ट कॉम्पैक्शन को उस तरह पार कर जाते हैं जैसे किसी कॉन्फ़िग फ़ाइल - का गद्य नहीं कर पाता। - - - -## समस्या - -एक बड़ा भाषा मॉडल स्टेटलेस है — एक कॉन्टेक्स्ट विंडो, हर कॉल पर मिटा दी जाती है। - -- उसके पास आपकी टीम ने जो पहले ही सीखा उसकी **कोई मेमोरी नहीं** है। -- उसके पास किसी एडिट से क्या टूटेगा इसका **कोई पूर्वाभास नहीं** है। -- उसके पास **कोई प्रवर्तित गार्डरेल्स नहीं** हैं — गद्य नियम कॉम्पैक्शन के बाद भुला दिए जाते हैं। - -और हर टूल अपनी ही कॉन्फ़िग फ़ाइल चाहता है (`CLAUDE.md`, `AGENTS.md`, `.cursor/rules`, -`GEMINI.md`, MCP…)। Forge वह संज्ञानात्मक सब्सट्रेट है जो तीन गायब चीज़ें उपलब्ध कराता है, -और वह कंपाइलर है जो उसे एक स्रोत से हर टूल तक पहुँचाता है। - -## थीसिस - -एक मॉडल कॉल्स के बीच आपके कोडबेस से नहीं सीख सकता: उसके वेट फ्रोज़ेन हैं और उसकी -वर्किंग मेमोरी हर प्रतिक्रिया के बाद मिट जाती है। मेमोरी, दूरदर्शिता और आत्म-जाँच -उसमें प्रॉम्प्ट नहीं की जा सकतीं — उन्हें _बाहर_ से देना पड़ता है। वही बाहरी परत -संज्ञानात्मक सब्सट्रेट है। औपचारिक रूप से, इनफ़रेंस एक स्थिर फ़ंक्शन `y = f(x)` है जिसमें -कॉल्स के बीच कोई स्टेट नहीं है; Forge वही स्टेट है। - - - - अपने नियम और सब्सट्रेट डिफ़ॉल्ट्स एक कैननिकल स्रोत में लिखें - (`source/rules.json`, `source/substrate.json`, `source/mcp.json`)। - - - `forge sync` उस स्रोत को हर टूल की नेटिव कॉन्फ़िग में कंपाइल करता है — नौ AI - कोडिंग टूल्स और MCP — कंटेंट-हैश हेडर के साथ, ताकि ड्रिफ्ट पहचानी जा सके और - पुनः चलाना नो-ऑप हो। - - - `forge substrate ""` एक डिटरमिनिस्टिक प्री-एक्शन पास चलाता है: अनुमान, - रूटिंग, पुनरुपयोग, कॉन्टेक्स्ट, ब्लास्ट रेडियस, स्कोप, और गोल एंकर। - - - केवल स्वतंत्र ओरैकल्स — टेस्ट्स, CI, कोई मानव स्वीकृति/रिवर्ट — किसी मेमोरी के - कॉन्फ़िडेंस को हिला सकते हैं, इसलिए ग़लत सबक जड़ हो जाने के बजाय क्षय होकर मिट जाता है। - - - -## आपको क्या मिलता है - -- **सत्रों और टीम-साथियों के बीच बनी रहने वाली मेमोरी।** हर सबक, तथ्य, और सत्यापित - पुनरुपयोग _प्रूफ-कैरीइंग मेमोरी (PCM)_ है — साक्ष्य-संदर्भित, कंटेंट-एड्रेस्ड - मेमोरी के लिए हमारा नाम: एक दावा जो अपने साक्ष्य के संदर्भ वहन करता है और तब तक - विश्वसनीय नहीं माना जाता जब तक कि स्वतंत्र ओरैकल्स उसके कॉन्फ़िडेंस को न्यूनतम सीमा से - ऊपर न उठा दें। "प्रूफ" वही साक्ष्य-मार्ग है, न कि कोई औपचारिक प्रमाण। -- **चीज़ें तोड़ने से पहले दूरदर्शिता।** पूछें "`verifyToken` बदलने से क्या टूटता है?" - और कोड ग्राफ़ से ब्लास्ट रेडियस पाएँ, जिसमें वे युग्मित फ़ाइलें भी शामिल हैं जिनका - नाम आपने कभी नहीं लिया। -- **ऐसे गार्डरेल्स जिन्हें भुलाया नहीं जा सकता।** डिटरमिनिस्टिक हुक संरक्षित पथ, - लागत बजट, और डूम-लूप डिटेक्शन लागू करते हैं — वे कॉन्टेक्स्ट कॉम्पैक्शन को पार कर जाते हैं। -- **ऐसा काम जो अंत तक पूरा हो।** एक कंप्लीशन गेट प्रति सत्र एक बार "done" रोकता है - जब कोड में परिवर्तन हुआ पर कोई डॉक या स्टेट आर्टिफ़ैक्ट साथ नहीं आया, और मरम्मत - चेकलिस्ट को उत्तर के रूप में देता है। -- **9 टूल्स के लिए एक कॉन्फ़िग।** अपने नियम एक बार लिखें; Forge हर टूल की नेटिव - कॉन्फ़िग निकालता है, साथ ही Roo और VS Code के लिए MCP। शून्य रनटाइम निर्भरताएँ — - एक Node CLI, git में सादी फ़ाइलें, कोई सर्वर नहीं। - -## Forge किन टूल्स को फ़ीड करता है? - -Forge **नौ टूल्स** के लिए कॉन्फ़िग निकालता है, साथ ही Roo Code और VS Code के लिए -एक MCP सर्वर: Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf/Devin, -Zed, और Continue। हर एक अपनी ही नेटिव फ़ाइल से वही नियम पढ़ता है। - -डिफ़ॉल्ट रूप से केवल एक ही MCP सर्वर वायर होता है — Forge का अपना (`src/cortex_mcp.js`) — -सब्सट्रेट चेक्स और मेमोरी रीड्स के लिए। `context7` जैसे थर्ड-पार्टी MCP सर्वर **ऑप्ट-इन** -हैं और तब तक डिस्क पर नहीं उतरते जब तक आप [`forge integrations add --yes`](/hi/cli/config#forge-integrations) -न चलाएँ। - -## ईमानदार सीमाएँ - -Forge हर जगह अपनी सीमा स्वयं बताता है। - - - Forge नियम-ड्रिफ्ट को **कम करता है, समाप्त नहीं करता।** यह एक पारदर्शिता और - विश्वसनीयता परत है, टेस्ट्स, समीक्षा, या निर्णय का विकल्प नहीं। - - -- **गार्ड्स केवल वही लागू करते हैं जो हुक के रूप में व्यक्त किया जा सके** (पथ, फ़ॉर्मैट, - डिफ़-साइज़, बजट)। अर्थपूर्ण नियम ("फ़ंक्शनल पसंद करें") गद्य रहते हैं और कभी-कभी - अनदेखे रह जाएँगे। -- **सत्यापन कम करता है, प्रमाणित नहीं करता।** क्रू वेरिफ़ायर और हैलुसिनेटेड-सिंबल - फ़्लैग समीक्षा भार कम करते हैं; वे कोड को सही सिद्ध नहीं करते। -- **कोई वेट-स्तरीय अधिगम नहीं।** `recall` / `cortex` केवल फ़ाइल-और-प्रॉम्प्ट मेमोरी है — न - RL, न फ़ाइन-ट्यूनिंग। -- **इम्पैक्ट ग्राफ़ regex-अनुमानित है** — रूढ़िवादी, कोई साउंड कॉल ग्राफ़ नहीं। -- **टेस्ट्स और मानव सुधार हमेशा जीतते हैं।** - - - Forge **बीटा** में है। कोर (`init`, `sync`, `substrate`, `impact`, `ledger`, guards) - परखा हुआ है और दैनिक उपयोग में है; कुछ फ़्लैग `1.0` से पहले बदल सकते हैं। - - -## अगले कदम - - - - इंस्टॉल करें, `forge init` चलाएँ, और अपना पहला कार्य सब्सट्रेट के माध्यम से पास कराएँ। - - - चार-परत कंपाइलर, प्रूफ-कैरीइंग मेमोरी, और प्री-एक्शन गेट। - - - हर कमांड, Core, Memory, Substrate, Quality, और Config के अनुसार समूहित। - - - एक टीम-साथी के लेजर को सादे git के ऊपर, संघर्ष-रहित तरीके से मिलाएँ। - - diff --git a/mintlify/hi/quickstart.mdx b/mintlify/hi/quickstart.mdx deleted file mode 100644 index 2900b23..0000000 --- a/mintlify/hi/quickstart.mdx +++ /dev/null @@ -1,107 +0,0 @@ ---- -title: "क्विकस्टार्ट" -description: "Forge इंस्टॉल करें, एक स्रोत से हर टूल का कॉन्फ़िग निकालें, और अपना पहला प्री-एक्शन गेट चलाएँ — लगभग 60 सेकंड में।" ---- - -शून्य से लेकर एक कॉन्फ़िगर किए गए रेपो और अपने पहले सब्सट्रेट चेक तक लगभग एक मिनट में पहुँचें। - -## 1. इंस्टॉल करें - - - -```bash Plugin (Claude Code / Codex) -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit -``` - -```bash npm (any tool) -npm install -g @codewithjuber/forgekit -``` - -```bash No registry -npm install -g github:CodeWithJuber/forgekit -``` - - - -प्लगइन पथ Claude Code और Codex के लिए अनुशंसित है — गार्ड्स स्वतः वायर हो जाते हैं -और मर्ज करने के लिए कुछ नहीं है। पूरे मैट्रिक्स के लिए [Installation](/hi/installation) -देखें, जिसमें symlink dev सेटअप भी शामिल है। - -## 2. एक रेपो कॉन्फ़िगर करें - - - - ```bash - cd ~/your-project - forge init - ``` - यह `AGENTS.md`, `CLAUDE.md`, `.gemini/settings.json`, `.aider.conf.yml`, और बाकी - निकालता है — साथ ही वह `.gitattributes` यूनियन-मर्ज नियम जो लेजर के लिए ज़रूरी है। - Claude Code, Codex, Cursor, Gemini, Aider, Copilot, Windsurf, Zed, और Continue - अब **समान** नियम पढ़ते हैं, प्रत्येक अपनी नेटिव फ़ाइल से। - - - ```bash - forge doctor - ``` - इंस्टॉल किए गए टूल्स, गार्ड्स, MCP ऑथ, और कॉन्फ़िग ड्रिफ्ट की पास/फ़ेल जाँच। - - - `source/rules.json` संपादित करें (या एक प्रति-रेपो `.forge/rules.json` रखें), फिर पुनः कंपाइल करें: - ```bash - forge sync - ``` - `sync` idempotent है — यह केवल वही पुनर्लिखित करता है जो बदला है। - - - -## 3. प्री-एक्शन गेट चलाएँ - -सब्सट्रेट वह परत है जो मॉडल द्वारा कोड एडिट करने से _पहले_ चलती है। एक कमांड पूरा -गेट चलाता है: - -```bash -forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" -# → assumption verdict · cheapest capable model · predicted blast radius -# (including files you didn't name) · scope clusters · verification checklist -``` - - - Claude Code पर सब्सट्रेट **हर प्रॉम्प्ट पर स्वचालित रूप से** एक `UserPromptSubmit` - हुक के माध्यम से चलता है — केवल सलाहकारी, साफ़ कार्यों पर मौन। हर दूसरा टूल एक - नेटिव कॉन्फ़िग नियम पाता है साथ ही 19 MCP टूल्स जिन्हें वह स्वयं कॉल कर सकता है। - - -अगर `forge substrate` `ASK FIRST` कहता है, तो एडिट करने से पहले लौटाए गए प्रश्न पूछें। -किसी भी परिवर्तनकारी बदलाव से पहले पूर्वानुमानित प्रभावित फ़ाइलें — ब्लास्ट रेडियस — पढ़ें। - -```bash -forge substrate "" --json # machine-readable verdict -forge impact # the blast radius on its own -``` - -## 4. अतिरिक्त सुविधाएँ खोजें - -```bash -forge atlas build # index this repo's symbols → .forge/atlas.json -forge atlas query useAuth # where is it defined? (cheaper than grep-and-read) -forge atlas has useAuth # does it exist? "not found" = likely hallucinated -forge recall add "db port" "Postgres is on 5433 here, not 5432" -forge catalog # the Start-Here index of everything -``` - -## 5. दूसरा दिन: लेजर सीख रहा है - -सब्सट्रेट ने दिन एक में जो कुछ सीखा वह `.forge/ledger/` में दावों के रूप में उतरा। -यह प्रूफ-कैरीइंग मेमोरी है — अब यह लाभ देना शुरू करती है: - -```bash -forge ledger stats # what the repo knows, by kind and trust -forge ledger blame # who minted a claim, every oracle outcome -forge reuse query "" # verified code you already have -``` - - - पढ़ें कि प्री-एक्शन गेट अपने चरणों को एक ही वर्डिक्ट में कैसे संयोजित करता है। - diff --git a/mintlify/zh-CN/changelog/overview.mdx b/mintlify/zh-CN/changelog/overview.mdx deleted file mode 100644 index 389a204..0000000 --- a/mintlify/zh-CN/changelog/overview.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "更新日志" -description: "Forge 的最新变化、功能更新与改进说明,帮助你及时掌握验证、会话与命令行工具的所有关键升级信息。" ---- - - - -## 更新内容 - -**`forge verify --deep` 现在返回四态结果。** 多视角共识运行不再折叠为二元的通过/失败结果。你将看到 `PASS`、`FAIL`、`INCOMPLETE` 或 `NOT_CONFIGURED` 中的一种,因此停滞的视角或未配置的仓库不会再被悄悄标记为绿色。只有 `PASS` 才算作已验证,而 `PASS` 现在还要求底层 `forge verify` 的测试状态也为 `PASS`——绿色的深度运行永远无法凌驾于红色的基础运行之上。 - -参见[质量命令](/zh-CN/cli/quality)和[验证门](/zh-CN/concepts/verification-gates)。 - -**完成门要求代码变更提供测试证据。** 对于任何触及源代码的会话,Stop 路径上的完成门不再单独接受 `forge handoff` 快照。你需要在会话的 diff 中包含一个测试文件,或针对当前变更提供一次新鲜通过的 `forge verify`。仅涉及文档、仅涉及配置以及其他非代码类会话不受影响。 - -当此门拦截时,修复检查清单现在会以 `forge verify` 作为首要步骤,以便在生成 handoff 快照之前先记录证据。参见[跨会话记忆](/zh-CN/concepts/cross-session-memory)。 - -**更清晰地界定钩子与护栏的定位。** Forge 的自动钩子是 Claude Code 专属的,并且——与其他所有咨询性信号一样——在你通过 `FORGE_ENFORCE=1` 显式启用之前默认处于关闭状态。这些护栏是纵深防御,而不是安全沙箱。运行时本身没有任何变化;文档与 CLI 文案只是与工具的实际行为保持一致。参见 [CLI 概览](/zh-CN/cli/overview)和[前置操作门](/zh-CN/concepts/pre-action-gate)。 - -## 修复 - -**密钥脱敏器现在会保留结构化的工具输出。** Bash、Read 和 Grep 等内置工具返回的是结构化对象,而先前的脱敏器会把这些响应字符串化——这意味着 Claude Code 会悄悄丢弃改写结果,未经脱敏的输出仍会保持可见。脱敏器现在会递归遍历响应:字符串就地清洗,数组和对象保留其键与结构,非字符串叶子则原样透传。纯字符串响应的脱敏结果与此前逐字节一致,而没有任何内容需要脱敏的响应则完全不会触发改写。 - -**`FORGE_GUARD_STRICT=1` 的退出状态不再被吞掉。** 脱敏器的 shell 包装脚本此前会强制返回干净的退出码,从而把严格模式的失败码对 Claude Code 隐藏起来,导致 `DEGRADED` 信号始终无法浮现。子进程的退出状态现在会端到端地向上传递,因此严格模式在 stderr 上的反馈能够真正抵达你。请注意,这个钩子是在工具已经执行之后才运行的——严格模式让脱敏器的降级变得显眼,但在调用真正执行之前将其拦截,是[前置操作门](/zh-CN/concepts/pre-action-gate)的职责。 - - diff --git a/mintlify/zh-CN/cli/config.mdx b/mintlify/zh-CN/cli/config.mdx deleted file mode 100644 index 03c4a34..0000000 --- a/mintlify/zh-CN/cli/config.mdx +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: "Config 命令" -description: "提供商、成本、看板、品牌、atlas、技术栈与可选 MCP 集成:config、cost、dash、brand、atlas、stack、report、tools、integrations。" ---- - -Config 组涵盖提供商、可观测性、代码图和技术栈检测。 - -## `forge config` - -提供商设置 —— 显示 / 切换 / 添加提供商,设置默认模型。 - -```bash -forge config # show current config -forge config switch -forge config add -``` - -## `forge cost` - -通过实测的阶段因子给出真实的每日花费。 - -```bash -forge cost # real per-day spend -forge cost --stages # measured per-stage cost factors -``` - - - **只报告实测过的阶段** —— 没有事件的阶段会显示"no data",而不是给出默认值。 - - -## `forge dash` - -基于账本、指标和爆炸半径的本地看板。 - -```bash -forge dash # localhost-only (default port 4242) -``` - -## `forge brand` - -打印当前生效的品牌 token 映射。 - -```bash -forge brand -``` - -品牌以单一 token(`brand.json`)存储;换品牌只需一次编辑。 - -## `forge atlas` - -构建 / 查询代码图。 - -```bash -forge atlas build [path] # walk the tree → .forge/atlas.json -forge atlas query "what calls Z" -forge atlas has # hallucinated-symbol check -``` - -atlas 是纯 JSON —— 任何工具都能读,不需要 MCP。 - -## `forge stack` - -从仓库的清单文件中检测其真实技术栈。 - -```bash -forge stack -``` - -读取 `package.json`、`pyproject.toml`、`go.mod`、`Cargo.toml`、`Gemfile`、 -`composer.json`、`pom.xml` / `build.gradle` 以及 `*.csproj`,报告语言、框架、包管理器,以及仓库**真正的**测试命令 —— 这些会喂给基座的验证清单。 - -## `forge report` - -生成仓库 Forge 状态的静态 HTML 报告 —— 把账本、指标和爆炸半径渲染到一个自包含的文件里,可以分享或存档。 - -```bash -forge report -``` - -## `forge tools` - -选择该仓库的主要 AI 编码工具,并接入匹配的 `.gitignore` 条目,让生成的配置和 `.forge/` 产物在你的环境下被正确忽略。 - -```bash -forge tools -``` - -## `forge integrations` - -选择性接入的第三方 MCP 服务器(例如 `context7`),在 Forge 生成配置的每一个工具中被非破坏性地统一管理 —— Claude Code、Codex、Cursor、Gemini、Continue 等。 - -第三方 MCP 服务器**默认不安装**。在你运行 `forge integrations add --yes` 之前,不会有任何东西落到磁盘上。 - -```bash -forge integrations # list opt-in servers with package + purpose -forge integrations add # dry-run: prints package, network, files it would touch -forge integrations add --yes # apply — write MCP config for every tool -forge integrations add --yes --adopt # also claim a same-name entry you already configured -forge integrations remove # reverse the add — deletes only forge-owned entries -``` - -### `add` 会写入什么 - -`add --yes` 会从同一份规范化的 spec 里把该服务器写入每个工具原生的 MCP 配置: - -- `.mcp.json`(Claude Code) -- `.cursor/mcp.json`(Cursor) -- `.gemini/settings.json`(Gemini) -- `.codex/config.toml` —— 作为一个 `# forge:managed:` 块,通过逐字节比较刷新 -- `.continue/mcpServers/.yaml` —— 每个被管理的服务器一个 forge 标记过的 YAML -- 以及 Forge 生成配置的其他工具 - -已安装的集合会记录在 `.forge/forge.config.json` 的 `mcp.integrations` 下,因此后续每次 `forge sync` 都会重新生成同样的服务器。stop-hook 的自动同步会对整个配置文件做逐字节比较,所以对该文件的手工编辑会被检测出来并修复。 - -### `--adopt` 的语义 - -如果某个工具的配置文件里已经存在同名服务器、而不是 Forge 放进去的,`add` **不会覆盖它**。它会报告该文件,并附上 `--adopt` 提示。加上 `--adopt` 重新运行以认领所有权 —— Forge 会把该条目记录在 `.forge/forge.config.json` 的 `mcp.adopted` 下,并从此接管它。 - -当你之前手工配置过某个服务器,现在想让 Forge 在每个工具间保持它同步时,就使用 `--adopt`。 - -### `remove` - -`forge integrations remove ` 是对 add 的反向操作。它只删除 forge 拥有的条目、块和文件 —— 用户自己配置过、且从未 `--adopt` 过的同名服务器不会被动。运行两次 `remove` 是无操作的。 - -```bash -forge integrations remove context7 -``` - -### `.forge/forge.config.json` - -单仓库的 Forge 状态 —— 同时也保存 `primaryTool`、`tools` 和 `profile` 的统一配置 —— 在两个键下记录选择性接入的集成: - -```json -{ - "mcp": { - "integrations": ["context7"], - "adopted": [] - } -} -``` - -未知的键会在写入时被原样保留。格式错误的文件不会被静默丢弃:读取时每个进程会在 stderr 上警告一次,写入方会拒绝覆盖一份无法解析的配置,而不是把它替换成默认值。 diff --git a/mintlify/zh-CN/cli/core.mdx b/mintlify/zh-CN/cli/core.mdx deleted file mode 100644 index fa3dab9..0000000 --- a/mintlify/zh-CN/cli/core.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "Core 命令" -description: "使用 init、sync、doctor、catalog、docs 与 update 引导并维护 Forge 仓库，涵盖 profile、settings、可逆卸载参数、无效 profile 中止行为，以及 FORGE_GUARD_STRICT 严格模式详解。" ---- - -Core 组用于引导一个仓库并保持其健康。 - -## `forge init` - -搭建该仓库的配置 —— 从一个共享源为每个工具生成配置。 - -```bash -forge init -``` - -生成 `AGENTS.md`、`CLAUDE.md`、`.gemini/settings.json`、`.aider.conf.yml` 以及其他文件(加上给 Roo Code 与 VS Code 的 MCP 服务器配置),以及账本需要的 `.gitattributes` union-merge 规则。 - -`forge init` 还会把 Forge 的 hooks 和 permissions 合并进**全局**的 `~/.claude/settings.json`,因此它会在写入前先声明该合并动作。合并过程是幂等的、有标记守护,并且不会覆盖用户自己的条目。 - -### Init 参数 - -| 参数 | 作用 | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--profile ` | 为该仓库选择策略 profile。接受 `minimal` 或 `standard`(默认)。无效值会在任何脚手架、`.forge/` 写入或合并之前中止。 | -| `--no-settings` | 完全跳过对全局 `~/.claude/settings.json` 的合并 —— 只写仓库级配置。 | -| `--remove-settings` | 回滚一次以往的 settings 合并。Forge 形态的 hooks、permissions、statusline 以及 `_forge` 标记会被移除;会先写一份带时间戳的备份,并保留你自己的条目。也会被 `install.sh --uninstall` 调用。 | -| `--settings-only` | 只合并全局 settings —— 不动仓库。被 `install.sh` 用来接线 hooks 与 permissions。 | - -如果 settings 合并被拒绝或出错,`forge init` 会以 exit 1 失败,并把原因写到 stderr,而不是报告成功。 - -### 策略 profiles - -`--profile` 选择 `forge sync` 编译进每个工具原生配置的规则集。只支持两种 profile: - -- **`standard`**(默认)—— 完整包:共享内存规则、影响分析,以及完整的护栏 hook 集。 -- **`minimal`** —— 面向小仓库或贡献者分叉的更精简规则集。 - -历史名称 `web-app`、`backend-service`、`library` 和 `regulated` 是 `standard` 的已弃用别名。它们仍然可用:`forge init` 会警告一次、存为 `standard`,而现存持有历史名称的配置也会按 standard sync。新仓库应直接使用 `standard`。任何其他值都是无效的,并会在 Forge 触碰该仓库之前中止。 - -```bash -forge init --profile minimal # leaner ruleset -forge init --no-settings # per-repo only, skip the global merge -forge init --remove-settings # reverse a past global merge -``` - -## `forge sync` - -把规范源重新编译为每个工具的原生配置文件。 - -```bash -forge sync -``` - -幂等 —— 只重写发生了变化的内容。修改 `source/rules.json` 或仓库级 `.forge/rules.json` 之后运行它。 - -## `forge doctor` - -对已安装工具、护栏、MCP 认证和配置漂移做健康检查。 - -```bash -forge doctor -``` - -跨工具、护栏、MCP 接线、配置漂移和更新状态给出通过/失败结果。每条路径都失败开放。当配置了自定义网关时,**gateway models** 一行会打印解析后的 `tier → model` 映射。 - -## `forge catalog` - -Start Here —— 列出每个工具、crew 和护栏,并附一行原因说明。 - -```bash -forge catalog -``` - -## `forge docs` - -文档 ↔ 代码 漂移。 - -```bash -forge docs check # registry reconcile — commands, env vars, MCP tools, CHANGELOG -forge docs sync # diff-driven stale-docs sweep -``` - - - 当命令、环境变量、MCP 工具或 CHANGELOG 与代码不一致时,`docs check` 会让 CI 失败。`docs sync` 扫描 diff 并报告 UPDATED / STALE / VERIFIED-UNAFFECTED。 - - -## `forge update` - -跨三种安装模式的自更新。 - -```bash -forge update # apply the update (git checkout or npm/copy install) -forge update --check # report whether a newer version is available -forge update --to # pin or downgrade to a specific version -``` - -每条路径都失败开放 —— 离线、没有上游或 detached HEAD 会返回 "unknown",从不作为错误。`FORGE_NO_UPDATE_CHECK=1` 可静默 doctor 的提示。 diff --git a/mintlify/zh-CN/cli/memory.mdx b/mintlify/zh-CN/cli/memory.mdx deleted file mode 100644 index aed503a..0000000 --- a/mintlify/zh-CN/cli/memory.mdx +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: "Memory 命令" -description: "跨会话与团队记忆:cortex、recall、remember、brain、ledger、reuse、handoff 和 decide —— 全部汇聚到携证账本。" ---- - -Memory 组管理跨会话与团队记忆。所有内容都汇聚到 `.forge/ledger/` 下的携证账本。模型说明见 [携证记忆](/zh-CN/concepts/proof-carrying-memory)。 - -## `forge cortex` - -自我纠正的项目记忆 —— 从纠错中挖掘出来的经验。 - -```bash -forge cortex status # what's been learned -forge cortex why # why a lesson applies here -``` - -## `forge recall` - -管理跨会话的个人记忆。 - -```bash -forge recall list # facts the recall-load guard injects next session -forge recall add "db port" "Postgres is on 5433 here, not 5432" -forge recall consolidate # summarize (advisory, human-reviewable) -``` - -## `forge remember` - -给该仓库的可移植记忆添加一条可提交到仓库的持久事实。 - -```bash -forge remember "" -``` - -## `forge brain` - -显示或重建可移植的项目记忆索引。 - -```bash -forge brain # show the index -forge brain --rebuild # rebuild it -``` - -## `forge ledger` - -携证记忆 —— 以内容寻址的声明存储。 - -```bash -forge ledger stats # what the repo knows, by kind and trust level -forge ledger verify # re-check claims are in normal form -forge ledger show # a claim and its evidence -forge ledger blame # who minted it, every oracle outcome, per-author trust -forge ledger query "" # retrieve by relevance -forge ledger ratify # human accept -forge ledger retract # tombstone a claim -forge ledger merge # fold a teammate's ledger in, conflict-free -forge ledger import # back-fill pre-ledger history into the ledger -``` - -加 `--personal` 使用每用户级别的账本。 - -## `forge reuse` - -携证代码缓存 —— 只有当证据仍然成立时才服务。 - -```bash -forge reuse query "" # verified code you already have -forge reuse mint "" --file # add an artifact to the cache -forge reuse stats # cache stats -``` - -## `forge handoff` - -有界的会话快照 —— 重写 `.forge/state.md`,每次会话开始时重新注入。 - -```bash -forge handoff "" --next "" -``` - -## `forge decide` - -只追加的决策日志 —— 在 `.forge/decisions.md` 中的 `D-####` 精简版 ADR 条目。 - -```bash -forge decide " — " -forge decide # read the log before re-deciding -``` - -## `forge know` - -把一条事实路由到它正确的存储归宿 —— 决定一段知识属于 `recall`、`remember`/`brain`、一个决策还是一条 cortex 经验,并把它落在那里。 - -```bash -forge know "" -``` - -## `forge deja` - -类似过往工作查找 —— 从账本中找出与你即将做的事类似的既有工作,让你复用证据而不是重新生成。 - -```bash -forge deja "" -``` diff --git a/mintlify/zh-CN/cli/overview.mdx b/mintlify/zh-CN/cli/overview.mdx deleted file mode 100644 index cd239da..0000000 --- a/mintlify/zh-CN/cli/overview.mdx +++ /dev/null @@ -1,62 +0,0 @@ ---- -title: "CLI 概览" -description: "所有 forge 命令按 Core、Memory、Substrate、Quality、Config 五组组织，并列出控制强制策略、命令输出与秘密再编辑的环境变量，包括 FORGE_ENFORCE、FORGE_GUARD_STRICT 与 FORGE_VERBOSE 的说明。" ---- - -`forge` 命令面以数据形式定义 (`src/commands.js`),并通过 `forge docs check` 与文档对账,因此任何命令的加入或消失都逃不过文档的注意。命令被组织成五个组。 - - - - 引导与维护:`init`、`sync`、`doctor`、`catalog`、`docs`、`update`。 - - - 跨会话与团队记忆:`cortex`、`recall`、`remember`、`brain`、`ledger`、`reuse`、`handoff`、`decide`。 - - - 预动作门及其各阶段:`substrate`、`preflight`、`route`、`impact`、`scope`、`context`、`anchor`、`diagnose`、`imagine`、`lean`。 - - - 验证与安全:`verify`、`scan`、`spec`、`taste`、`uicheck`、`harden`。 - - - 提供商、成本、看板、品牌、atlas、技术栈:`config`、`cost`、`dash`、`brand`、`atlas`、`stack`。 - - - -## 约定 - -- **默认建议模式。** 设置 `FORGE_ENFORCE=1` 可让基座把最强的信号(空洞的 prompt、无法组装的必需上下文、爆炸半径超过默认的 25 文件阈值)变为硬阻断。 -- **默认安静。** 每个命令的 `Forge — …` 标题只是品牌装饰,藏在 `--verbose` / `FORGE_VERBOSE` 后面;命令会先输出结果。 -- **管道友好输出。** 管道下是纯文本;TTY 下加上品牌调色板颜色和置信度进度条。`NO_COLOR` 关闭颜色,`FORCE_COLOR=1` 强开。 -- **`--json`** 在基座和大多数分析命令上可用,便于脚本化。 - -## 环境变量 - -| 变量 | 作用 | -| ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `FORGE_ENFORCE=1` | 把基座最强的建议信号转为硬阻断。 | -| `FORGE_GUARD_STRICT=1` | 把 secret 脱敏器的 `DEGRADED` 警告升级为阻断式退出。默认情况下,脱敏失败会向 stderr 打印 `secret redaction DEGRADED` 并放行输出;严格模式则拒绝输出任何脱敏器无法完全清洗的内容。适用于 CI 或共享机器 —— 那里一行未脱敏的内容比一条失败的命令更糟。 | -| `FORGE_NO_UPDATE_CHECK=1` | 静默 `forge doctor` 中的 "commits behind upstream" 提示。 | -| `FORGE_NO_HINT=1` | 静默一次性提示你运行 `forge init` 的初始化提示。 | -| `FORGE_VERBOSE=1` | 显示默认隐藏的每命令横幅 (`Forge — …`)。 | -| `FORGE_EMBED=1` | 为记忆召回开启 embedding 层(MinHash 仍是零依赖默认)。 | -| `FORGE_LEDGER_ONLY=0` | 应急开关。仅 ledger 现为默认——记忆只存放在 `.forge/ledger` 中，旧的 `lessons/*.md` 与 fact 文件不再写入。设为 `0` 可恢复旧的文件存储。 | - - - 运行 `forge --help` 获取始终最新的列表,或运行 `forge catalog` 查看每个工具、crew 和护栏并附一行原因说明的 Start-Here 索引。 - - -## 更新的命令与标志 - -这些命令与参数均已可用。它们记录在各自的组页面并在文中标注: - -| 命令 / 参数 | 组 | 作用 | -| ---------------------- | -------- | ----------------------------------------------- | -| `forge know` | Memory | 把一条事实路由到它正确的存储归宿。 | -| `forge deja` | Memory | 类似过往工作查找。 | -| `forge precommit` | Quality | 提交级验证门。 | -| `forge radar` | Quality | 依赖时效性同心圆。 | -| `forge report` | Config | 仓库 Forge 状态的静态 HTML 报告。 | -| `forge tools` | Config | 主工具选择 + gitignore 接线。 | -| `forge verify --deep` | Quality | 多镜头共识验证。 | -| `forge update --to` | Core | 锁定或回退到指定版本。 | diff --git a/mintlify/zh-CN/cli/quality.mdx b/mintlify/zh-CN/cli/quality.mdx deleted file mode 100644 index ff62882..0000000 --- a/mintlify/zh-CN/cli/quality.mdx +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "Quality 命令" -description: "验证与安全:verify、scan、spec、taste、uicheck 和 harden。" ---- - -Quality 组是验证与安全的入口。这些如何组合,详见 [验证门](/zh-CN/concepts/verification-gates)。 - -## `forge verify` - -独立验证门 —— 测试 + 幻觉符号 + 溯源。 - -```bash -forge verify -forge verify --deep # multi-lens consensus -``` - -`forge verify --deep` 报告的是四态 `status`,而不是简单的通过 / 失败: - -| Status | 含义 | -| ---------------- | ------------------------------------------------------------------------------------ | -| `PASS` | 所有镜头都一致通过,**并且**核心 `forge verify` 的测试状态也是 `PASS`。 | -| `FAIL` | 至少有一个镜头报告了真实失败。 | -| `INCOMPLETE` | 有镜头未能完成(超时、崩溃、依赖缺失)—— 视为未被证明。 | -| `NOT_CONFIGURED` | 该仓库没有接入任何镜头 —— 实际上什么也没被检查。 | - -只有 `PASS` 才算已验证。`--deep` 有意拒绝在底层 `forge verify` 测试状态不是 `PASS` 时把共识提升为 `PASS`,因此一次绿色的 deep 运行始终意味着底层运行也是绿色的。 - -## `forge scan` - -skill 门 —— 在安装前审查某个 skill 或 MCP 服务器是否存在注入 / RCE / 泄露风险。 - -```bash -forge scan -``` - -## `forge spec` - -规约即契约 —— init (OpenSpec)、锁定、并检查漂移。 - -```bash -forge spec init -forge spec lock -forge spec check -``` - -## `forge taste` - -为该仓库启用一个 UI 品味工具(不带参数会列出选项)。 - -```bash -forge taste # list the profiles -forge taste # brutalist · corporate · editorial · minimalist · playful -``` - -写入 `DESIGN.md` 并参数化 `uicheck design` 门的阈值。 - -## `forge uicheck` - -确定性 UI 检查。 - -```bash -forge uicheck contrast # WCAG contrast ratio -forge uicheck fingerprint # deterministic design fingerprint -forge uicheck design # slop-distance + conformance gate -forge uicheck visual # Playwright-rendered check (opt-in tier) -``` - -## `forge harden` - -接入安全控制 —— gitleaks pre-commit + 沙箱设置。 - -```bash -forge harden -``` - -## `forge precommit` - -提交级门 —— 在 commit 时运行验证底线,以便在部分或未验证的工作落库之前捕获它们。 - -```bash -forge precommit -``` - -## `forge radar` - -依赖时效性同心圆 —— 按当前程度把项目的依赖分组,让陈旧或漂移的依赖在咬人之前浮现。 - -```bash -forge radar -``` - -如何阅读这些环,见 [保持依赖时效](/zh-CN/guides/radar-deps) 指南。 diff --git a/mintlify/zh-CN/cli/substrate.mdx b/mintlify/zh-CN/cli/substrate.mdx deleted file mode 100644 index 14b06bc..0000000 --- a/mintlify/zh-CN/cli/substrate.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: "Substrate 命令" -description: "预动作门及其可单独调用的各阶段:substrate、preflight、route、impact、scope、context、anchor、diagnose、imagine 和 lean。" ---- - -Substrate 组即预动作门。`forge substrate` 把其余命令合成为单一裁决;每个阶段也可以单独调用。流水线详情见 [预动作门](/zh-CN/concepts/pre-action-gate)。 - -## `forge substrate` - -一个预动作门:假设、路由、影响、范围、记忆、验证。 - -```bash -forge substrate "" -forge substrate "" --json -``` - -如果返回 `okToProceed:false`,在编辑前先提出返回的 `assumption.questions`。 - -## `forge preflight` - -假设检查 —— 任务提到的、仓库中没有定义的东西。 - -```bash -forge preflight "" -``` - -## `forge route` - -为一个任务推荐性价比最高、能胜任的模型。 - -```bash -forge route "" -forge route gateway # emit LiteLLM gateway config -``` - -## `forge impact` - -从 atlas 图中预测某个符号或文件的爆炸半径。 - -```bash -forge impact -``` - -## `forge scope` - -把文件分解成独立的簇 —— 外加你没点名的耦合文件。 - -```bash -forge scope -``` - -## `forge context` - -有预算的上下文组装 + 完整性门 —— 一次编辑**需要**知道的东西。 - -```bash -forge context "" -``` - -对预测的编辑集合使用集合覆盖来组装一个有预算的上下文,套用一层压缩阶梯,并报告计算出的缺失集合。 - -## `forge anchor` - -目标漂移检查 —— 你实际(git)变更是否仍然对准既定目标? - -```bash -forge anchor set "" # persist the goal across sessions -forge anchor show -forge anchor clear -``` - -## `forge diagnose` - -死循环检查 —— 记录一次失败;相同签名出现 3 次会生成一份诊断 + 升级。 - -```bash -forge diagnose "" -``` - -## `forge imagine` - -后果模拟 —— 为某个任务预测的破坏点 + 最小空跑测试集。 - -```bash -forge imagine "" -forge imagine "" --run # execute the minimal suite sandboxed -``` - -## `forge lean` - -范围最小性 (M5) —— 衡量 diff 的足迹与任务要求之间的差距。 - -```bash -forge lean -``` - - - `route`、`impact`、`scope`、`context`、`anchor` 和 `lean` 都会在 `forge substrate` 里运行。当你只需要单一信号时才单独调用它们。 - diff --git a/mintlify/zh-CN/concepts/config-compiler.mdx b/mintlify/zh-CN/concepts/config-compiler.mdx deleted file mode 100644 index e312ec0..0000000 --- a/mintlify/zh-CN/concepts/config-compiler.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "四层配置编译器" -description: "一次编写基座;forge sync 把它编译到每个工具的原生配置中。四层是大脑的表达方式;编译器是它的交付方式。" ---- - -你一次编写基座。`forge sync` 把这个源编译到每个工具的原生配置中。四层是_大脑的表达方式_;编译器是_大脑的交付方式_。 - -```mermaid -flowchart TD - S["source/ · rules.json · substrate.json · mcp.json"] -->|"forge sync — content-hash + DO-NOT-EDIT headers"| N["native configs · CLAUDE.md · AGENTS.md · .cursor · .gemini · .aider"] - S -. configures .-> L - subgraph L["the four layers"] - direction LR - T["tools · model-invoked skills"] - C["crew · isolated sub-agents"] - G["guards · deterministic hooks"] - M["mcp · atlas + substrate server"] - end -``` - -## 一个源,多个发射器 - -规则**只写一次**(`source/rules.json`);一个确定性编译器 (`forge sync`) 以每个工具的原生格式发射,附带内容哈希头,因此漂移可检测,重复运行是无操作的。没有任何规则被写两次。规范源由三个文件组成: - -| 源文件 | 存放什么 | -| ----------------------- | -------------------------------------------------------------------- | -| `source/rules.json` | 规范的工程规则(git、测试、安全、风格)。 | -| `source/substrate.json` | 认知基座默认值 —— 阈值、路由、LLM 旋钮。 | -| `source/mcp.json` | 发射到每个工具的 MCP 服务器定义。 | - -## 四层 - -每一层都有品牌名,并且跨工具发射。 - - - - `~/.forge/tools/` → `~/.claude/skills/`。模型可调用的 skill,遵循 `SKILL.md` 标准(`name` + `description` 前置元数据)。 - - - `~/.forge/crew/` → `~/.claude/agents/`。上下文隔离的子代理,例如 scout、verifier 和 frontend-verifier。 - - - `~/.forge/guards/` → `settings.json` 钩子。**唯一_强制_而非建议的层。** 一个 guard 是模型无法漂移的确定性钩子。`CLAUDE.md` 中的散文规则被承认后会在压缩之后被遗忘;guard 不会。任何可强制的不变量都属于这里。 - - - Forge 提供一个 stdio 服务器 (`src/cortex_mcp.js`),暴露 19 个 MCP 工具:基座检查 (`substrate_check` / `predict_impact` / `assumption_gate` / …)、记忆的读_与_写 (`forge_remember`、ledger ratify/retract),以及运维/健康。 - - - -跨越四层的关注点:**atlas**(代码图)、**lean**(极简性 —— 既作为一个工具,也作为一个 Stop 阶段的 guard 出货,所以不管模型是否调用它都会生效)、**recall**(记忆)。 - -## 用 guard 代替散文 - -模型可以漂移的规则活在散文里;它**绝对不能**违反的规则活在 guard(确定性 shell 钩子)里。guard 不会在上下文压缩后被遗忘。 - - - 把每一条可强制的不变量从 `CLAUDE.md` 中挪到 guard 里,让散文保持精简。这是 Forge 设计中最重要的一条纪律。 - - -## 经过验证的跨工具发射矩阵 - -Forge 为**九个工具**发射配置,加上给 Roo Code 与 VS Code 的 MCP 服务器。每一行都对照过厂商文档。 - -| 工具 | 原生目标 | Forge 如何发射 | -| ------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------- | -| **Claude Code** | `CLAUDE.md`(+ `.claude/rules/*.md`、`settings.json`) | 首行是 `@AGENTS.md` 的精简 `CLAUDE.md`;guards → settings | -| **Codex** | 原生 `AGENTS.md`(32 KiB 上限) | 根目录规范 `AGENTS.md` **就是**源 | -| **Cursor** | `AGENTS.md` + `.cursor/rules/*.mdc` | 扁平规则用 `AGENTS.md`;需要作用域时用 `.mdc` | -| **Gemini** | `GEMINI.md`,或通过 `context.fileName` 选用 `AGENTS.md` | 写 `.gemini/settings.json` 以避免第二份副本 | -| **Aider** | 通过 `.aider.conf.yml` 的 `read:` 指向的 `CONVENTIONS.md` | 生成含 `read: AGENTS.md` 的 `.aider.conf.yml` | -| **Copilot** | 根 `AGENTS.md` + `.github/copilot-instructions.md` | 依赖根 `AGENTS.md`;可选 `.github` 指针 | -| **Windsurf/Devin** | `AGENTS.md` 自动发现(上限 6k/12k 字符) | 根 `AGENTS.md` 在上限之内;区分 `.windsurf` 与 `.devin` | -| **Zed** | 含 `AGENTS.md` 的优先级列表首匹配 | 发射 `AGENTS.md`;doctor 标注任何被遮蔽的遗留文件 | -| **Continue** | `.continue/rules/*.md` + `.continue/mcpServers/*.yaml` | 发射规则文件加上 Forge MCP 服务器配置 | - -Roo Code 和 VS Code 通过 `forge init` 拿到 Forge MCP 服务器(`.roo/mcp.json`、`.vscode/mcp.json`),而非规则文件。 - - - **字符上限是真的。** Codex 在 32 KiB 处截断,Windsurf 在 6k/12k 处截断。`forge sync` 会强制一个源大小预算,以防配置被悄悄截断。 - diff --git a/mintlify/zh-CN/concepts/cross-session-memory.mdx b/mintlify/zh-CN/concepts/cross-session-memory.mdx deleted file mode 100644 index f2e89f4..0000000 --- a/mintlify/zh-CN/concepts/cross-session-memory.mdx +++ /dev/null @@ -1,73 +0,0 @@ ---- -title: "跨会话记忆" -description: "会话锚定、完成门、handoff 快照和决策日志 —— 消灭会话失忆和半途而废的那一层。" ---- - -这一层要消灭两种失败模式:**半途而废的工作**(代码变了,但依赖它的产物没跟上)和**会话失忆**(下一场会话重新假设这场会话已知的东西)。指令提升正确行为的_概率_;确定性钩子保证一个_底线_。 - -## 会话锚定 - -在 `SessionStart` 时 (`src/session.js`),Forge 每次会话记录一次 `HEAD`,清理一周前的会话产物,并注入一份新鲜的定位: - - - - 从过往纠错中挖出的 cortex 经验。 - - - 既定目标,用来衡量漂移。 - - - 上一场会话写下的有界 `.forge/state.md`。 - - - 近期提交和未提交变更 —— 是证据,不是先验。 - - - -新会话依据证据而非先验来定位。 - -## 完成门 - -Stop 路径上唯一被允许回答的 guard 是 `completion-gate.sh` (`src/gate.js`)。它同步运行;负责挖掘经验的 `cortex.sh stop` 始终在分离进程中,永远不会阻塞。 - -变更集是**会话范围**的:committer time 大于等于会话开始时间的提交涉及到的文件,加上工作树变更减去 `SessionStart` 时快照的脏文件 —— 因此已存在的编辑、分支切换和 `git pull` 永远不会被算到代理头上。 - - - 如果代码动了但没有对应的文档或状态产物跟进,该门会**阻断一次**,阻断原因就是修复清单。其他情况一律放行,内部错误也一律放行(失败开放)。`FORGE_STOPGATE=0` 可禁用它。 - - -对于改动了代码的会话,该门还要求**测试证据** —— 要么会话 diff 中有一份测试文件,要么针对当前变更有一次新鲜且通过的 `forge verify`。仅凭一份 `forge handoff` 快照,已不再能通过代码变更那一支门。 - -修复清单指向能收尾这项工作的工具: - -```bash -forge verify # record the test evidence for code changes -forge docs sync # sweep the diff for stale doc mentions -forge handoff "" --next "" # write the bounded session snapshot -forge decide " — " # record a choice so no session re-decides it -``` - -## Handoff 与决策 - -两个存储让知识跨越会话: - -| 存储 | 语义 | -| ---------------------- | ------------------------------------------------------------------------------------ | -| `.forge/state.md` | 一份有界的**重写**(快照)—— loader 成本永远保持 `O(bound)`。 | -| `.forge/decisions.md` | 只追加的**精简版 ADR**(`D-####`),并带一份机器可读的决策账本副本。 | - -两者在写入时都会拒绝密钥。`state.md` 在每次会话开始时被重新注入;`decisions.md` 在重新决定过往会话已经定下的事项之前会被读一遍。 - -```bash -forge handoff "" --next "" -forge decide " — " -forge decide # read the log before re-deciding -``` - -## 由 diff 驱动的文档扫描 - -`forge docs sync` 回答 diff 形式的问题:变化过的标识符(路径、定义、被调用的符号,来自新增_与_删除两侧的行)对每一份文档产物做扫描 → UPDATED / STALE(带 file:line 命中)/ VERIFIED-UNAFFECTED,并记录原因。它是纯粹的报告工具;完成门提供牙齿。 - - - `recall` 和 `cortex` 只是文件和提示词记忆 —— **不是**权重级学习。合并是一个可能出现幻觉的摘要,所以它一直是建议性的、可人工审阅的、且不含密钥。 - diff --git a/mintlify/zh-CN/concepts/model-routing.mdx b/mintlify/zh-CN/concepts/model-routing.mdx deleted file mode 100644 index 9658c88..0000000 --- a/mintlify/zh-CN/concepts/model-routing.mdx +++ /dev/null @@ -1,61 +0,0 @@ ---- -title: "模型路由" -description: "一份确定性、可 diff 的评分表在分发前挑出性价比最高、能胜任的模型层级 —— 并为自托管网关提供一个保底重映射。" ---- - -Forge 在分发**之前**推荐性价比最高、能胜任任务的模型,依据是一份你可以在仓库中阅读的确定性评分表 (`src/model_tiers.json`)。与在代理内部于请求时决策的网关不同,路由决策在 git 中是可见且可 diff 的。 - -## 推荐一个层级 —— `forge route` - -```bash -forge route "" # cheapest capable model tier for the task -forge route gateway # emit LiteLLM gateway config -``` - -推荐使用的是在标注样本库(英文 + Hinglish 行)上的示例 k-NN 数学,基于重叠相似度指标并有置信度门 —— 不是关键词查表。 - - - 从推荐的 `route.tier` 开始,只有当外部验证器失败之后再升级,永远不要预防性升级。这样既压得住花费,又不会在任务确实需要能力时封顶。 - - -## 先意图,再层级 - -路由与意图检测 (`src/intent.js`) 共享同一套数学:一段 prompt 通过同一个示例 k-NN 估计器映射到意图。注意两者使用不同的停用集合 —— route 把泛化动词(`fix` / `add` / `build`)视为复杂度噪声,而这些动词恰好是意图信号。 - -## 层级表 - -层级表 (`src/model_tiers.json`) 按家族(haiku / sonnet / opus / fable)固定了公开的 Anthropic 模型 ID。文档中的价格通过 docs check 与这份文件对账,所以散文和表格无法漂移。 - -## 自托管网关重映射 - -自托管的 LiteLLM 或代理网关会提供自己命名的模型,直接把库存 ID 原样发过去会 404。当配置了非默认的网关 base URL 时,Forge (`src/gateway_model_map.js`) **每个进程仅一次**拉取 `GET /v1/models`,并对每个层级家族对被宣告的每一个 id 打分: - - - - 家族关键词(haiku / sonnet / opus / fable)必须匹配 —— 这是硬门。 - - - 在同一家族内,由层级名字 token 的 `setOverlap` 系数挑出最佳匹配。 - - - 平局时倾向于最接近规范名的 id。 - - - - - 该重映射**只**在解析出的 id 是一个_库存_ ID 时才咨询网关 —— 显式的 `.forge/providers.json` 别名或 `ANTHROPIC_MODEL` 覆盖永远不会被触碰。当没有网关、`/v1/models` 不可达或家族不匹配时,它会保底为库存 ID,因此直连 `api.anthropic.com` 的用户会得到逐字节一致的结果。 - - -`forge doctor` 的 **gateway models** 行会打印解析后的 `tier → model` 映射,便于校验。 - -## 提供商与成本 - -```bash -forge config # show / switch / add providers, set the default model -forge cost # real per-day spend -forge cost --stages # measured per-stage cost factors -``` - - - `forge cost --stages` **只报告实测过的阶段** —— 没有事件的阶段会显示"no data",而不是给出默认值。一个数字在被测量之前只是假设。 - diff --git a/mintlify/zh-CN/concepts/pre-action-gate.mdx b/mintlify/zh-CN/concepts/pre-action-gate.mdx deleted file mode 100644 index 894719b..0000000 --- a/mintlify/zh-CN/concepts/pre-action-gate.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: "预动作门" -description: "forge substrate 在模型编辑代码之前有序地运行一趟检查,并返回单一裁决 —— 假设、路由、影响、范围、记忆和验证。" ---- - -**认知基座** —— 在模型编辑代码_之前_运行的层。`forge substrate ""`(以及 MCP 工具 `substrate_check`)有序地运行一趟检查并返回单一裁决。它把可单独调用的各阶段 —— `preflight`、`route`、`atlas`、`impact`、`reuse`、`context`、`scope`、`lean`、`anchor`、`verify` —— 合成一份预动作契约。 - -```mermaid -flowchart TD - RE["referenced entities"] --> INTAKE - subgraph INTAKE["intake"] - direction LR - PF["preflight · assumption gap"] --> RT["route · cheapest tier"] - end - INTAKE --> ANALYSIS - subgraph ANALYSIS["analysis"] - direction LR - AT["atlas · code graph"] --> IM["impact · blast radius"] --> PT["predict · failing tests"] --> RU["reuse · cache hit?"] - end - ANALYSIS --> SAFETY - subgraph SAFETY["safety + fit"] - direction LR - CX["context · completeness gate"] --> SC["scope · coupled files"] --> ME["memory · recall + lessons"] --> MN["minimality · lean footprint"] --> GA["goal-anchor · drift check"] - end - SAFETY --> VD["verdict"] -``` - -## 三个阶段 - - - - **preflight** 找出假设缺口 —— 任务提到、但仓库未定义的东西。**route** 挑出性价比最高、能胜任的模型层级。 - - - **atlas** 读取代码图,**impact** 计算爆炸半径,**predict** 点名可能失败的测试,**reuse** 检查是否命中已验证缓存。 - - - **context** 运行完整性门,**scope** 浮出耦合文件,**memory** 注入 recall + 经验,**minimality** 衡量 lean 足迹,**goal-anchor** 检查漂移。 - - - -## 爆炸半径 - -**爆炸半径** —— 一次编辑被预测会影响的文件集合,来自代码图。`forge impact` 计算它;流水线在模型触碰任何东西之前把它浮出来。 - -```bash -forge impact verifyToken # predicted impacted files for a symbol -forge impact src/auth.js # …or for a file -``` - -## 默认建议模式 - -裁决**默认是建议性**的 —— 它只报告,不阻断。设置 `FORGE_ENFORCE=1` 可以把最强的信号变成硬阻断: - - - - preflight 找不到可行的意图 —— 任务规格不足。 - - - 完整性门无法覆盖预测的编辑集合。 - - - 受影响集合超过默认的约 25 文件阈值。 - - - -其他一切都留作可以由人覆盖的警告。 - - - 在 Claude Code 上,整个门通过 `UserPromptSubmit` 钩子在**每个 prompt 上自动运行** —— 对干净任务保持静默。`forge substrate "" --json` 提供机器可读的裁决用于脚本化。 - - -## 运行它 - -```bash -forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" -forge substrate "" --json -``` - -如果裁决为 `ASK FIRST`,在编辑前先提出返回的 `assumption.questions` —— 不要猜规格不足的任务。从推荐的 `route.tier` 开始,只有当外部验证器失败之后再升级,永远不要预防性升级。 - - - 记忆阶段从携证账本中读取。 - diff --git a/mintlify/zh-CN/concepts/proof-carrying-memory.mdx b/mintlify/zh-CN/concepts/proof-carrying-memory.mdx deleted file mode 100644 index 0860ac1..0000000 --- a/mintlify/zh-CN/concepts/proof-carrying-memory.mdx +++ /dev/null @@ -1,95 +0,0 @@ ---- -title: "携证记忆" -description: "每一条被存下的事实、经验或复用产物都是一个自带证据的声明 —— 只有当独立裁决方把它的置信度抬升到阈值之上时才被信任。" ---- - -**携证记忆 (PCM)** —— 每一条被存下的事实、经验或复用产物都是一个自带证据的_声明_。只有当独立裁决方(测试、CI、人类的接受/回滚)把它的置信度抬升到阈值之上时,它才会被信任。错误的经验会衰减而不是固化。 - - - "携证记忆"是我们对**有证据引用、以内容寻址的记忆**的称呼 —— 声明由其内容的哈希寻址,并链接到支持它的裁决方结果。"证明"是那条证据链加上置信度规则,**不是**形式化机器验证过的证明;流程中不存在定理证明器。 - - -## 一个存储,多个写入者 - -所有记忆子系统都汇聚到同一个存储。`recall`、`remember`/`brain`、`cortex` 经验、`reuse` 产物、以及死循环的 `diagnose` 结果都会以内容寻址的方式把声明写入 `.forge/ledger/`。 - -```mermaid -flowchart LR - subgraph EV["local events"] - direction TB - E1["recall / remember"] - E2["cortex lesson"] - E3["reuse mint"] - E4["diagnose"] - end - EV -->|"content-addressed claims"| LG["(.forge/ledger)"] - O["independent oracles · tests · CI · human accept/revert"] -->|"append evidence · move confidence"| LG - TM["teammate ledgers"] <-->|"git union-merge · conflict-free"| LG - LG --> RV["merged read view · recall list · lesson inject · brain index"] -``` - -## 为什么它能无冲突地收敛 - -因为一个声明的字节是 `(kind, body, scope)` 的纯函数,每个副本计算出的身份都一样 —— 所以队友的账本可以通过纯 git 无冲突地合并。 - -机制上: - -- **证据与墓碑都是只追加的**,并做哈希去重。 -- **置信度 (`val`)** 是一个带衰减的 Beta 后验,只能由裁决方推动。 -- **合并是一个 join-semilattice** —— 已被属性测试验证为可交换、可结合、幂等 —— 因此账本无论以何种顺序合并都能收敛。 - - - `forge init` 会生成账本需要的 union-merge `.gitattributes` 规则;`forge ledger merge ` 可以合并任意另一棵账本树。完整决策见 ADR-0006(携证记忆)。 - - -## 只有裁决方能移动置信度 —— 其他任何东西都不行 - -只有独立的裁决方能移动一条记忆的置信度: - - - - 一次通过、能演练该声明的测试会提升它的置信度。 - - - 一次绿色的流水线是该声明仍然成立的独立证据。 - - - 显式的接受或者回滚是最强的信号。 - - - -无法验证的证据会被一张封闭的 `ORACLES` 表 (`src/ledger.js`) 拒绝。未经审阅的知识衰减为_不确定_,而不是删除 —— 沉睡的声明保留下来供审计,永远不会被静默移除。 - -## 账本表面 - -```bash -forge ledger stats # what the repo knows, by kind and trust level -forge ledger verify # re-check claims are in normal form -forge ledger show # a claim and its evidence trail -forge ledger blame # who minted it, every oracle outcome, per-author trust -forge ledger query "" # retrieve claims by relevance -forge ledger ratify # human accept -forge ledger retract # tombstone a claim -forge ledger merge # fold a teammate's ledger in, conflict-free -forge ledger import # bridge legacy stores into the ledger -``` - -加 `--personal` 使用每用户级别的账本。 - -## 复用缓存也是携证的 - -`forge reuse` 是一个携证的代码缓存。一段生成的产物只有在其证据仍然成立时才会被再次服务 —— 置信度在阈值之上**并且**它的 atlas 依赖仍然可解析。否则就会穿透到生成流程,并在返回途中铸一条新声明。 - -```mermaid -flowchart LR - SP["spec"] --> FP["fingerprint · MinHash + LSH"] - FP --> LD["match ladder · exact to near to adapt to miss"] - LD --> GT{"confidence >= floor AND deps resolve?"} - GT -->|"yes"| SV["serve · proof holds"] - GT -->|"miss"| GN["generate"] - GN -->|"mint claim"| MT["(.forge/ledger)"] -``` - - - MinHash 的近似匹配在非常短的 spec 上偏弱。可选的嵌入后端 (`FORGE_EMBED`) 可以提升这一点;MinHash 仍是零依赖的默认。 - diff --git a/mintlify/zh-CN/concepts/verification-gates.mdx b/mintlify/zh-CN/concepts/verification-gates.mdx deleted file mode 100644 index 054a3d9..0000000 --- a/mintlify/zh-CN/concepts/verification-gates.mdx +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: "验证门" -description: "独立验证、幻觉符号标记、规约即契约、skill 门 —— 这些你可以运行的检查会降低但不认证正确性。" ---- - -没有可运行的检查(测试、构建退出码、截图),就不算"完成"。Forge 的每一道验证门都多接住一次。若每任务的漏检率是 `1 − p`、门的捕获率是 `c`,那么静默漏检降到 `(1 − p)(1 − c)`,而这里的每一道门都是多一个 `c`。 - - - **验证是减少而不是认证。** Crew 验证者和幻觉符号标记降低审查负担;它们不证明代码正确。测试和人工修正始终最优先。 - - -## 独立验证 —— `forge verify` - -一道独立的门:它运行仓库真正的测试,标记幻觉符号,并检查溯源。 - -```bash -forge verify # tests + hallucinated-symbol + provenance -forge verify --deep # multi-lens consensus — several independent checks must agree -``` - - - `--deep` 升级为多镜头共识:该变更必须通过多个独立的验证镜头,而不只是一个。 - - -`forge verify --deep` 报告的是四态 `status`,而不是二元的通过 / 失败: - -- `PASS` —— 所有镜头都一致通过,**并且**核心 `forge verify` 的测试状态也是 `PASS`。只有这个状态才算已验证。 -- `FAIL` —— 至少有一个镜头报告了真实失败。 -- `INCOMPLETE` —— 有镜头未能完成(超时、崩溃、依赖缺失)。没有推翻任何东西,但也没有证明任何东西。 -- `NOT_CONFIGURED` —— 该仓库没有接入任何镜头,所以 `--deep` 没有可以检查的东西。 - -`PASS` 蕴含底层 `PASS` 的规则是有意为之:一次绿色的 deep 共识永远无法跑赢红色的底层运行,因此底层测试镜头上的 `INCOMPLETE` 或 `NOT_CONFIGURED` 会把 deep 结果降级为同样的状态。 - -## 幻觉符号标记 —— `forge atlas has` - -`forge atlas has ` 是幻觉检查:如果模型调用了一个不在代码图中的符号,这道门会标记它。 - -```bash -forge atlas build # index this repo's symbols → .forge/atlas.json -forge atlas has useAuth # "not found" = likely hallucinated -``` - -atlas 特意采用纯 JSON —— Codex、Cursor、Gemini 和 Aider 都可以通过 CLI 或纯 `jq` 读取 `.forge/atlas.json`,消费端无需 MCP 依赖。 - -## 规约即契约 —— `forge spec` - -把行为绑定到一份规约并检测漂移: - -```bash -forge spec init # scaffold an OpenSpec contract -forge spec lock # lock the current spec as the contract -forge spec check # report drift against the locked contract -``` - -## skill 门 —— `forge scan` - -在安装 skill 或 MCP 服务器之前审查其是否存在注入、RCE 或泄露风险: - -```bash -forge scan -``` - - - 一次干净的扫描**不是安全认证**。内置启发式只捕获已知攻击形态(critical)和一部分高严重度模式;通过意味着_"未检测到关键签名"_,而不是_"可以安全安装"_。始终自己审阅源码、权限、包溯源和网络行为。一个**高**严重度发现即便不硬阻断,也不会被标记为安全。外部扫描器是可选加装,除非你启用,否则不会发起网络调用。 - - -## 加固 —— `forge harden` - -接入把密钥和不安全变更挡在门外的安全控制: - -```bash -forge harden # gitleaks pre-commit + sandbox settings -``` - -## 提交级门 —— `forge precommit` - - - `forge precommit` 是一道提交级门 —— 在 commit 时运行验证底线,以便在部分或未验证的工作落库之前捕获它们。 - - -## 完成门 —— 需要测试证据 - -Stop 路径上的完成门(见 [跨会话记忆](/zh-CN/concepts/cross-session-memory))不再接受一份 agent handoff 作为代码变更已完成的证明。任何触碰了源码的会话,该门都要求**真实的测试证据**: - -- 会话 diff 中改动了一份测试文件,**或** -- 针对当前变更有一次新鲜且通过的 `forge verify` 记录。 - -仅凭一份 `forge handoff` 快照不满足该门 —— 它记录的是意图,不是验证。如果两种证据都不存在,该门会**阻断一次**,阻断原因就是修复清单: - -```bash -forge verify # produce the test evidence -forge handoff "" --next "" # then snapshot the session -``` - -只涉及文档、只涉及配置以及其他非代码类会话不受影响 —— 测试证据的要求只在会话 diff 实际改动了代码时才会触发。 - -## UI 检查 —— `forge uicheck` - -确定性 UI 检查,前三个镜头不用 LLM 也不用截图: - -```bash -forge uicheck contrast # WCAG contrast ratio -forge uicheck fingerprint # deterministic design fingerprint -forge uicheck design # slop-distance + conformance gate -forge uicheck visual # Playwright-rendered check (opt-in tier) -``` - -搭配 `forge taste` 选一个视觉方向(brutalist、corporate、editorial、minimalist、playful)并参数化 `design` 门的阈值。 diff --git a/mintlify/zh-CN/guides/radar-deps.mdx b/mintlify/zh-CN/guides/radar-deps.mdx deleted file mode 100644 index d5d8833..0000000 --- a/mintlify/zh-CN/guides/radar-deps.mdx +++ /dev/null @@ -1,54 +0,0 @@ ---- -title: "用 radar 保持依赖时效" -description: "forge radar 按时效性把依赖分组到同心圆里,让陈旧或漂移的依赖在咬人之前浮现。" ---- - - - `forge radar` 已可用。本指南描述它如何契合既有的依赖时效性纪律;请运行 `forge --help` 以确认你所安装版本中的可用性。 - - -Forge 的一条工程规则是:_在添加依赖之前,从实时来源核实当前最佳选项,并优先使用项目已经用了的东西。_ `forge radar` 让依赖的当前状态可见,让这条规则有数据可依。 - -## 思路:时效同心圆 - -`forge radar` 按当前程度把项目的依赖分组到同心的**时效圆**里 —— 从中心的最新到边缘的陈旧或漂移。读这些环是回答"我们让什么漂移了?"最快的方法,不需要手工审计每个包。 - -```bash -forge radar -``` - -## 依赖清单来自哪里 - -Radar 基于与 `forge stack` 相同的清单读取逻辑,后者从依赖清单中检测仓库的真实技术栈: - -```bash -forge stack # languages, frameworks, package managers, real test commands -``` - -由于检测是数据驱动的、且跨生态(`package.json`、`pyproject.toml`、`go.mod`、`Cargo.toml`、`Gemfile`、`composer.json`、`pom.xml` / `build.gradle`、`*.csproj`)都失败开放,radar 可以对 `stack` 理解的同一批清单进行时效性推理。 - -## 在循环中使用它 - - - - 在添加或升级依赖之前,运行 `forge radar` 看看已经有哪些依赖在漂移。 - - - 如果一个能胜任、且当前的依赖已经在内圈里,就复用它,而不是再引入一个新依赖 —— 最小的贴合改动获胜。 - - - 当你确实要升级或替换一个依赖时,记下原因: - ```bash - forge decide "bump to — " - ``` - 这样未来会话读到这个选择,而不是重新争论一遍。 - - - - - Radar 报告时效性,不替你升级。把它的环当作给人类决策的建议性输入 —— 并在称之为"完成"之前用仓库真实的测试 (`forge verify`) 校验任何一次升级。 - - - - 依赖升级之后,运行 Quality 门 —— `forge verify` 和 `forge precommit`。 - diff --git a/mintlify/zh-CN/guides/team-memory.mdx b/mintlify/zh-CN/guides/team-memory.mdx deleted file mode 100644 index f367581..0000000 --- a/mintlify/zh-CN/guides/team-memory.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "用账本做团队记忆" -description: "通过纯 git 无冲突地合并队友的账本 —— 没有服务器、没有同步服务,只是以任意顺序都能收敛的文件。" ---- - -基座学到的一切 —— cortex 经验、`forge remember` 事实、已验证的复用产物 —— 都作为内容寻址的声明落在一个 git 原生的账本 (`.forge/ledger/`) 里,天生按无冲突方式合并。没有服务器,也没有同步服务;只是 git 中的文件。 - -## 三条命令搞定团队记忆 - - - - ```bash - forge init - ``` - 这会生成账本需要的 `.gitattributes` union-merge 规则等内容。 - - - Cortex 经验和 `forge remember` 事实会在你工作时把声明影子写入账本 —— 没有额外命令要跑。 - - - ```bash - git pull && forge ledger merge - ``` - 任意顺序 —— 合并是无冲突的。 - - - -## 为什么它不会冲突 - -一条声明的字节是 `(kind, body, scope)` 的纯函数,所以每个副本对同样的知识都会算出同样的身份。合并是一个 join-semilattice —— 已被属性测试验证为可交换、可结合、幂等 —— 所以两个队友的账本无论谁先同步都会收敛到同样的状态。 - -```mermaid -flowchart LR - A["your ledger"] <-->|"git union-merge · conflict-free"| B["teammate ledger"] - A --> M["merged read view"] - B --> M - M --> R["recall list · lesson inject · brain index"] -``` - - - 独立铸出的相同知识会收敛为**一条**声明,并在其溯源中保留每一位作者。 - - -## 信任与溯源 - -置信度只能被独立的裁决方 —— 测试、CI、人类的接受/回滚 —— 移动,所以导入队友的账本并不盲目相信他们的笔记;它导入的是他们的_证据_。 - -```bash -forge ledger blame # who minted a claim, every oracle outcome, per-author trust -forge ledger stats # the merged view, by kind and trust level -forge ledger verify # confirm every claim is in normal form -``` - -## 团队范围内的复用 - -一旦队友的已验证代码进入合并后的账本,你就可以带着它的证据复用它: - -```bash -forge reuse query "" -``` - -命中会指向可运行、经测试确认的代码,以及能证明它的 `forge ledger blame` —— 复用它,而不是重新生成。 - - - 沉睡的声明保留下来供审计,永远不会被删除;未经审阅的知识衰减为_不确定_,而不是被删除。账本是一条证据链,不是一个可以静默丢失的缓存。 - diff --git a/mintlify/zh-CN/guides/zero-config-onboarding.mdx b/mintlify/zh-CN/guides/zero-config-onboarding.mdx deleted file mode 100644 index 225a228..0000000 --- a/mintlify/zh-CN/guides/zero-config-onboarding.mdx +++ /dev/null @@ -1,80 +0,0 @@ ---- -title: "引导式、低配置上手" -description: "五分钟进入生产:安装一次,配置仓库一次,做一个任务,然后在第二天看到账本开始发挥效益 —— 引导式、低配置,不是零操作。" ---- - -Forge 目标是**引导式、低配置上手** —— 一个新仓库通常在大约五分钟内就能投入使用。安装一次、配置仓库一次、做一个任务,然后账本在第二天开始发挥效益。(是低配置,不是零配置:你仍然要安装 CLI、在每个仓库运行 `forge init`,并且某些路径假定有 Bash、Git 和 `jq`。) - -```mermaid -flowchart TD - I["forge init"] --> Cfg["every tool configured from one source"] - Cfg --> Work["you work as usual"] - Work --> Gate["substrate checks each task · ask first? · which model? · what breaks?"] - Gate --> Edit["agent edits, with guardrails"] - Edit --> Learn["cortex learns from corrections"] - Learn -.->|next task is smarter| Work -``` - -## 1. 安装(一次) - -推荐路径不需要令牌也不需要克隆: - - - -```bash Plugin -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit -``` - -```bash CLI -npm install -g @codewithjuber/forgekit -``` - - - -```bash -forge doctor # everything green? -``` - -## 2. 配置一个仓库(每个仓库一次) - -```bash -cd ~/your-project -forge init # emits AGENTS.md, CLAUDE.md, .gemini/settings.json, .aider.conf.yml … -``` - -现在 Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf、Zed 和 Continue 都从各自的原生文件读取**同样的**规则。以后修改规则,编辑 `source/rules.json`(或放一个仓库级的 `.forge/rules.json`),然后运行 `forge sync`。 - -## 3. 使用认知基座 - -```bash -forge substrate "" # ask/route/impact/scope/reuse/context/memory/verify in one pass -forge substrate "" --json -forge impact # the blast radius on its own -``` - -如果 `forge substrate` 返回 `ASK FIRST`,在编辑前先提出返回的问题。 - -## 4. 使用附加功能 - -```bash -forge atlas build # index this repo's symbols → .forge/atlas.json -forge atlas query useAuth # where is it defined? -forge atlas has useAuth # does it exist? "not found" = likely hallucinated -forge recall add "db port" "Postgres is on 5433 here, not 5432" -forge catalog # the Start-Here index of everything -``` - -## 5. 第二天:账本开始学习 - -第一天基座学到的一切 —— cortex 经验、被记住的事实、已验证的代码 —— 都作为声明落在 `.forge/ledger/` 中。 - -```bash -forge ledger stats # what the repo knows, by kind and trust level -forge ledger blame # who minted a claim, every oracle outcome -forge reuse query "" # verified code you already have -``` - - - 下一步:通过纯 git 无冲突地合并队友的账本。 - diff --git a/mintlify/zh-CN/installation.mdx b/mintlify/zh-CN/installation.mdx deleted file mode 100644 index 1458b09..0000000 --- a/mintlify/zh-CN/installation.mdx +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: "安装" -description: "同一棵树上的三扇门:plugin marketplace、npm 全局安装、以及无需 registry 的 github: 安装 —— 外加贡献者用的符号链接开发环境。" ---- - -Forge 遵循**一棵树、三扇门**的设计:plugin manifest、加固安装脚本和 npm bin 都指向同一份 `global/` + `source/` 树。根据你的工具挑一个通道即可。 - -## 选择一个通道 - - - - 面向 Claude Code 和 Codex。护栏自动接线,无需合并。 - - - 面向任何工具。从公共 npm registry 安装 `forge` CLI。 - - - 无需 registry —— 直接从仓库安装。 - - - 克隆 + `npm link`,或运行 `bash install.sh` 建立符号链接。 - - - -## 要求 - -- **Node.js >= 20** -- **零运行时依赖** —— 一切都是 Node 内置模块。可选层(`FORGE_EMBED` 嵌入,`uicheck visual` 需要的 Playwright)是可选加装,不引入必需依赖。 - -## Plugin marketplace - -面向 Claude Code 和 Codex 的推荐路径,不需要令牌也不需要克隆: - -```bash -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit -``` - -Plugin 通过 `${CLAUDE_PROJECT_DIR}` 接入护栏,使预动作门与完成门在后台生效。 - -## npm 全局 - -从公共 npm 安装,可服务任何工具: - -```bash -npm install -g @codewithjuber/forgekit -forge doctor # everything green? -``` - -## 无 registry 的 github: 安装 - -```bash -npm install -g github:CodeWithJuber/forgekit -``` - -## 贡献者 / 本地开发 - - - -```bash npm link -git clone https://github.com/CodeWithJuber/forgekit.git -cd forgekit -npm link -``` - -```bash install.sh (symlink setup) -git clone https://github.com/CodeWithJuber/forgekit.git -cd forgekit -bash install.sh -``` - - - -这个安装脚本经过加固:幂等、基于符号链接、带备份,不使用 `curl | sh`。 - -## 校验 - -无论走哪个通道,都可以确认安装: - -```bash -forge doctor # tools, guards, MCP auth, config drift, update status -``` - - - `forge doctor` 还会为 git 检出显示一条不烦人的"落后于上游几个提交"提示。设置 `FORGE_NO_UPDATE_CHECK=1` 可以静默它。每一条路径都失败开放 —— 离线或 detached HEAD 报告"unknown",从不作为错误。 - - -## 保持 Forge 最新 - -```bash -forge update --check # report whether a newer version is available -forge update # apply the update (git checkout or npm/copy install) -forge update --to # pin or downgrade to a specific version -``` - - - 转到快速开始,运行 `forge init` 并进行你的第一次基座检查。 - diff --git a/mintlify/zh-CN/introduction.mdx b/mintlify/zh-CN/introduction.mdx deleted file mode 100644 index a58dee3..0000000 --- a/mintlify/zh-CN/introduction.mdx +++ /dev/null @@ -1,101 +0,0 @@ ---- -title: "Forge：面向 AI 编码代理的认知基座" -description: "Forge 是每个无状态模型都缺失的认知基座 —— 记忆、前瞻与护栏 —— 以原生配置的形式交付给每一个 AI 编码代理。" ---- - -**为每一个 AI 编码代理提供同一个大脑。** 大语言模型是无状态的:一个上下文窗口,每次调用都被清空。它不记得团队学到过什么,不预知一次编辑会破坏什么,也没有强制执行的护栏。Forge -(`@codewithjuber/forgekit`) 就是**认知基座** —— 一个在模型编辑代码_之前_运行的层,负责提供有证据引用的、以内容寻址的记忆(我们称之为"携证记忆"),启发式的影响前瞻,以及强制执行的护栏 —— 再加上一个 -**跨工具的配置编译器**,把这个大脑作为原生配置一次性交付到每一个工具中。Claude Code 是测试最深入的集成;其他工具会收到原生配置和 MCP 工具,但实际使用中打磨得较少。 - - - - 携证记忆,跨会话和跨队友持续存在。每一条经验、事实和已验证的复用都是一个自带证据的声明。 - - - 一次编辑的爆炸半径 —— 从代码图中读取的、被预测将会触及的文件集合,包括你从未点名的耦合文件。 - - - 确定性的钩子强制执行模型永远不能违反的规则。它们能挺过一次上下文压缩,而配置文件里的散文规则做不到。 - - - -## 问题 - -大语言模型是无状态的 —— 一个上下文窗口,每次调用都被清空。 - -- 它**没有记忆**,不知道团队已经学到过什么。 -- 它**没有前瞻**,不知道一次编辑会破坏什么。 -- 它**没有强制护栏** —— 散文形式的规则在一次压缩后就被遗忘。 - -而每个工具都要自己的配置文件(`CLAUDE.md`、`AGENTS.md`、`.cursor/rules`、`GEMINI.md`、MCP……)。Forge 就是那个认知基座,补齐这三件缺失的事,并且用一个编译器从单一源交付给每一个工具。 - -## 论点 - -模型无法在两次调用之间从你的代码库中学习:它的权重被冻结,工作记忆在每次回答后被清空。记忆、前瞻和自检无法通过提示词植入模型 —— 它们必须从_外部_供给。这个外部的层就是认知基座。形式化地说,推理是一个固定函数 `y = f(x)`,调用之间没有状态;Forge 就是那个状态。 - - - - 把你的规则和基座默认值写在一个规范源中 - (`source/rules.json`、`source/substrate.json`、`source/mcp.json`)。 - - - `forge sync` 把这个源编译为每个工具的原生配置 —— 九个 AI 编码工具外加 MCP —— 并加上内容哈希头,因此漂移可检测,重复运行是无操作的。 - - - `forge substrate ""` 运行一次确定性的预动作检查:假设、路由、复用、上下文、爆炸半径、范围以及目标锚点。 - - - 只有独立的裁决方 —— 测试、CI、人类的接受/回滚 —— 才能改变记忆的置信度,因此错误的经验会衰减而不是固化。 - - - -## 你能得到什么 - -- **跨会话、跨队友持续存在的记忆。** 每一条经验、事实和已验证的复用都是_携证记忆 (PCM)_ —— 我们对有证据引用、以内容寻址的记忆的称呼:一个携带其证据引用的声明,只有当独立裁决方把它的置信度抬升到阈值以上时才会被信任。"证明"指的是那条证据链,而不是形式化证明。 -- **在你破坏东西之前预知。** 询问"修改 `verifyToken` 会破坏什么?",从代码图得到爆炸半径,包括你从未点名的耦合文件。 -- **不会被遗忘的护栏。** 确定性钩子强制执行保护路径、成本预算和死循环检测 —— 它们能挺过一次上下文压缩。 -- **端到端能收尾的工作。** 一个完成门在每次会话中最多阻断一次:当代码变更了但没有对应的文档或状态产物跟进时,阻断的原因就是修复清单。 -- **一份配置服务 9 个工具。** 一次编写规则;Forge 生成每个工具的原生配置,外加给 Roo 和 VS Code 的 MCP。零运行时依赖 —— 一个 Node CLI、纯文本文件放在 git 里,没有服务器。 - -## Forge 会喂给哪些工具? - -Forge 为**九个工具**生成配置,并提供一个用于 Roo Code 与 VS Code 的 MCP 服务器: -Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf/Devin、Zed 和 Continue。 -每一个都从自己的原生文件读取同样的规则。 - -默认接线的 MCP 服务器只有 Forge 自己的那一个(`src/cortex_mcp.js`)—— 用于基座检查和记忆读取。诸如 `context7` 之类的第三方 MCP 服务器是**选择性接入**的,在你运行 [`forge integrations add --yes`](/zh-CN/cli/config#forge-integrations) 之前,不会有任何东西落到磁盘上。 - -## 诚实的边界 - -Forge 到处标明自己的天花板。 - - - Forge **减少但不消除**规则漂移。它是一层透明度和可靠性,不是测试、审查或判断的替代品。 - - -- **护栏只强制那些可以表达为钩子的东西**(路径、格式、diff 大小、预算)。语义规则("倾向函数式")仍然是散文,有时会被忽略。 -- **验证是减少而不是认证。** Crew 验证者和幻觉符号标记降低了审查负担;它们不证明代码正确。 -- **没有权重级学习。** `recall` / `cortex` 只是文件和提示词记忆 —— 没有 RL,没有微调。 -- **影响图是基于正则表达式的近似** —— 保守估计,而不是精确的调用图。 -- **测试和人工修正始终最优先。** - - - Forge 处于 **beta**。核心部分(`init`、`sync`、`substrate`、`impact`、`ledger`、护栏)经过测试并每日使用;部分参数在 `1.0` 之前可能变动。 - - -## 下一步 - - - - 安装、运行 `forge init`,并让你的第一个任务通过基座。 - - - 四层编译器、携证记忆和预动作门。 - - - 每个命令,按 Core、Memory、Substrate、Quality 和 Config 分组。 - - - 通过纯 git 无冲突地合并队友的账本。 - - diff --git a/mintlify/zh-CN/quickstart.mdx b/mintlify/zh-CN/quickstart.mdx deleted file mode 100644 index 5d7d931..0000000 --- a/mintlify/zh-CN/quickstart.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "快速开始" -description: "安装 Forge、从单一源生成每个工具的配置、并运行你的第一个预动作门 —— 大约 60 秒。" ---- - -从零到配置完成的仓库和第一次基座检查,只需要大约一分钟。 - -## 1. 安装 - - - -```bash Plugin (Claude Code / Codex) -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit -``` - -```bash npm (any tool) -npm install -g @codewithjuber/forgekit -``` - -```bash No registry -npm install -g github:CodeWithJuber/forgekit -``` - - - -对于 Claude Code 和 Codex,推荐使用 plugin 方式 —— 护栏会自动接线,无需手动合并。完整的安装矩阵(包括符号链接开发环境)见 [安装](/zh-CN/installation)。 - -## 2. 配置一个仓库 - - - - ```bash - cd ~/your-project - forge init - ``` - 这会生成 `AGENTS.md`、`CLAUDE.md`、`.gemini/settings.json`、`.aider.conf.yml` 等 —— 外加账本需要的 `.gitattributes` union-merge 规则。Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf、Zed 和 Continue 现在都从各自的原生文件读取**同样的**规则。 - - - ```bash - forge doctor - ``` - 对已安装工具、护栏、MCP 认证和配置漂移进行通过/失败检查。 - - - 编辑 `source/rules.json`(或放一个仓库级的 `.forge/rules.json`),然后重新编译: - ```bash - forge sync - ``` - `sync` 是幂等的 —— 只重写发生了变化的内容。 - - - -## 3. 运行预动作门 - -基座是在模型编辑代码_之前_运行的层。一条命令就能运行整个门: - -```bash -forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" -# → assumption verdict · cheapest capable model · predicted blast radius -# (including files you didn't name) · scope clusters · verification checklist -``` - - - 在 Claude Code 上,基座通过 `UserPromptSubmit` 钩子在**每个 prompt 上自动运行** —— 仅作建议,对干净任务保持静默。其他每个工具都会获得一条原生配置规则,加上它可以自己调用的 19 个 MCP 工具。 - - -如果 `forge substrate` 返回 `ASK FIRST`,在编辑前先提出返回的问题。在任何变更之前,阅读预测的受影响文件 —— 也就是爆炸半径。 - -```bash -forge substrate "" --json # machine-readable verdict -forge impact # the blast radius on its own -``` - -## 4. 探索附加功能 - -```bash -forge atlas build # index this repo's symbols → .forge/atlas.json -forge atlas query useAuth # where is it defined? (cheaper than grep-and-read) -forge atlas has useAuth # does it exist? "not found" = likely hallucinated -forge recall add "db port" "Postgres is on 5433 here, not 5432" -forge catalog # the Start-Here index of everything -``` - -## 5. 第二天:账本开始学习 - -第一天基座学到的一切都作为声明落在 `.forge/ledger/` 中。这就是携证记忆 —— 现在它开始发挥效益: - -```bash -forge ledger stats # what the repo knows, by kind and trust -forge ledger blame # who minted a claim, every oracle outcome -forge reuse query "" # verified code you already have -``` - - - 阅读预动作门如何把各阶段合成为单一裁决。 - diff --git a/mintlify/zh-Hans/changelog/overview.mdx b/mintlify/zh-Hans/changelog/overview.mdx deleted file mode 100644 index 5469766..0000000 --- a/mintlify/zh-Hans/changelog/overview.mdx +++ /dev/null @@ -1,26 +0,0 @@ ---- -title: "更新日志" -description: "了解 Forge 的最新变化、功能更新与关键行为调整，帮助你及时掌握验证门与会话记忆等核心能力的演进。" ---- - - - -## 更新内容 - -**`forge verify --deep` 现在会报告四种状态的结果。** 多视角共识运行不再折叠成"通过/失败"的二元结果。你会看到 `PASS`、`FAIL`、`INCOMPLETE` 或 `NOT_CONFIGURED` 中的一种，因此停滞的视角或未配置的仓库不再会被悄悄识别为通过。只有 `PASS` 才算作已验证，并且 `PASS` 现在还要求底层 `forge verify` 测试状态也为 `PASS`——一次绿色的深度运行永远无法盖过一次红色的基础运行。 - -参见 [质量命令](/zh-Hans/cli/quality) 与 [验证门](/zh-Hans/concepts/verification-gates)。 - -**完成门要求代码变更提供测试证据。** 对于任何触及源代码的会话，Stop 路径的完成门都不再仅凭一次 `forge handoff` 快照就予以放行。你需要会话 diff 中包含测试文件，或者针对当前变更提供一次新鲜的、通过的 `forge verify`。仅涉及文档、仅涉及配置以及其他非代码会话不受影响。 - -当完成门拦截时，修复清单现在会以 `forge verify` 起头，以便先记录证据，再进行 handoff 快照。参见 [跨会话记忆](/zh-Hans/concepts/cross-session-memory)。 - -**更清晰地定位 hooks 与护栏的角色。** Forge 的自动化 hooks 仅面向 Claude Code，并且——与其他所有咨询性信号一样——默认关闭，直到你通过 `FORGE_ENFORCE=1` 主动启用。这些护栏是纵深防御，而不是安全沙箱。运行时本身没有任何变化；只是文档与 CLI 文案与工具的实际行为保持一致。参见 [CLI 总览](/zh-Hans/cli/overview) 与 [前置操作门](/zh-Hans/concepts/pre-action-gate)。 - -## 修复 - -**秘密脱敏器现在会保留结构化的工具输出。** Bash、Read、Grep 等内置工具会返回结构化对象，而此前的脱敏器会把这些响应字符串化——这意味着 Claude Code 会悄悄丢弃改写结果，未脱敏的输出依然可见。现在脱敏器会递归遍历响应：字符串就地清洗，数组与对象保持其键与结构，非字符串叶子节点则原样透传。纯字符串响应的脱敏结果与此前逐字节一致，并且当响应中没有任何需要脱敏的内容时，不会发出任何改写。 - -**`FORGE_GUARD_STRICT=1` 的退出状态不再被吞掉。** 脱敏器的 shell 包装脚本此前会强制以干净状态退出，把严格模式的失败码对 Claude Code 隐藏了起来，因此 `DEGRADED` 信号从未浮现出来。现在子进程的退出状态会被端到端透传，严格模式的 stderr 反馈才真正能到达你面前。请注意，该 hook 是在工具执行之后才运行——严格模式会让脱敏器降级变得显眼，但在调用发生之前拦截它，仍然是 [前置操作门](/zh-Hans/concepts/pre-action-gate) 的职责。 - - diff --git a/mintlify/zh-Hans/cli/config.mdx b/mintlify/zh-Hans/cli/config.mdx deleted file mode 100644 index 7125419..0000000 --- a/mintlify/zh-Hans/cli/config.mdx +++ /dev/null @@ -1,142 +0,0 @@ ---- -title: "Config 命令" -description: "提供方、成本、仪表盘、品牌、atlas、stack 与可选 MCP 集成:config、cost、dash、brand、atlas、stack、report、tools、integrations。" ---- - -Config 分组覆盖提供方、可观察性、代码图和技术栈检测。 - -## `forge config` - -提供方配置——展示 / 切换 / 添加提供方,设置默认模型。 - -```bash -forge config # 显示当前配置 -forge config switch -forge config add -``` - -## `forge cost` - -通过实测的阶段系数计算的真实每日花销。 - -```bash -forge cost # 真实的每日花销 -forge cost --stages # 实测的每阶段成本系数 -``` - - - **仅报告已实测的阶段**——没有事件的阶段会显示 “no data”,绝不使用默认值。 - - -## `forge dash` - -对 ledger、指标与爆炸半径的本地仪表盘。 - -```bash -forge dash # 仅本机(默认端口 4242) -``` - -## `forge brand` - -打印当前生效的品牌 token 映射。 - -```bash -forge brand -``` - -品牌以单个 token(`brand.json`)存储;换品牌只需一次编辑。 - -## `forge atlas` - -构建 / 查询代码图。 - -```bash -forge atlas build [path] # 遍历目录树 → .forge/atlas.json -forge atlas query "what calls Z" -forge atlas has # 幻觉符号检查 -``` - -atlas 是纯 JSON——任何工具都能读,不需要 MCP。 - -## `forge stack` - -从清单文件检测本仓库的真实技术栈。 - -```bash -forge stack -``` - -读取 `package.json`、`pyproject.toml`、`go.mod`、`Cargo.toml`、`Gemfile`、 -`composer.json`、`pom.xml` / `build.gradle` 和 `*.csproj`,并报告语言、框架、包管理器,以及仓库**实际**的测试命令——这些会喂进基座的验证清单。 - -## `forge report` - -生成本仓库 Forge 状态的静态 HTML 报告——把 ledger、指标和爆炸半径渲染成一个自包含文件,可分享或归档。 - -```bash -forge report -``` - -## `forge tools` - -选择本仓库的主用 AI 编码工具,并接线相应的 `.gitignore` 条目,让生成的配置与 `.forge/` 产物按你的设置被正确忽略。 - -```bash -forge tools -``` - -## `forge integrations` - -按需接入的第三方 MCP 服务器（例如 `context7`），在 Forge 生成配置的每一个工具上以非破坏的方式统一管理——Claude Code、Codex、Cursor、Gemini、Continue,以及其余全部。 - -第三方 MCP 服务器**不会**默认安装。在你运行 `forge integrations add --yes` 之前,任何东西都不会落到磁盘上。 - -```bash -forge integrations # list opt-in servers with package + purpose -forge integrations add # dry-run: prints package, network, files it would touch -forge integrations add --yes # apply — write MCP config for every tool -forge integrations add --yes --adopt # also claim a same-name entry you already configured -forge integrations remove # reverse the add — deletes only forge-owned entries -``` - -### `add` 会写入什么 - -`add --yes` 会依据同一份规范化描述,把服务器写入每个工具的原生 MCP 配置: - -- `.mcp.json`(Claude Code) -- `.cursor/mcp.json`(Cursor) -- `.gemini/settings.json`(Gemini) -- `.codex/config.toml`——作为一个 `# forge:managed:` 块,通过逐字节比对刷新 -- `.continue/mcpServers/.yaml`——每个受管服务器一份带 forge 标记的 YAML -- 以及 Forge 生成配置的其余工具 - -已安装集合会记录在 `.forge/forge.config.json` 的 `mcp.integrations` 下,因此之后每次 `forge sync` 都会重新生成同一批服务器。stop-hook 的自动同步会对整份配置文件进行逐字节比对,所以对该文件的手工改动会被检测出来并被修复。 - -### `--adopt` 语义 - -如果某个同名服务器已经存在于某个工具的配置文件里,且不是 Forge 放进去的,`add` **不会覆盖它**。它会报告该文件并附上 `--adopt` 提示。带 `--adopt` 重新运行即可接管所有权——Forge 会把该条目记录在 `.forge/forge.config.json` 的 `mcp.adopted` 下,并从此开始管理它。 - -当你此前手工配置过某个服务器,现在希望 Forge 帮你在所有工具间保持一致时,就用 `--adopt`。 - -### `remove` - -`forge integrations remove ` 会撤销一次 add。它只删除 forge 拥有的条目、块和文件——由用户配置且从未 `--adopt` 过的同名服务器会被保留原样。连续运行两次 `remove` 是无操作。 - -```bash -forge integrations remove context7 -``` - -### `.forge/forge.config.json` - -每个仓库的 Forge 状态——这份统一配置同时保存 `primaryTool`、`tools` 和 `profile`——会在两个键下记录按需接入的集成: - -```json -{ - "mcp": { - "integrations": ["context7"], - "adopted": [] - } -} -``` - -未知键在写入时会原样往返保留。格式有误的文件不会被静默丢弃:读取时每个进程会在 stderr 上告警一次,写入方会拒绝覆盖一个无法解析的配置,而不是用默认值把它替换掉。 diff --git a/mintlify/zh-Hans/cli/core.mdx b/mintlify/zh-Hans/cli/core.mdx deleted file mode 100644 index 3539fed..0000000 --- a/mintlify/zh-Hans/cli/core.mdx +++ /dev/null @@ -1,102 +0,0 @@ ---- -title: "Core 命令" -description: "使用 init、sync、doctor、catalog、docs 与 update 命令引导并维护 Forge 仓库，讲解 profile、settings、可逆卸载参数，无效 profile 提前中止，以及 FORGE_GUARD_STRICT 严格模式。" ---- - -Core 分组负责引导一个仓库并保持它健康。 - -## `forge init` - -搭建本仓库的配置——从一份共享源生成每个工具的配置。 - -```bash -forge init -``` - -生成 `AGENTS.md`、`CLAUDE.md`、`.gemini/settings.json`、`.aider.conf.yml` 等 -(以及给 Roo Code 和 VS Code 的 MCP 服务器配置),外加 ledger 所需的 `.gitattributes` union-merge 规则。 - -`forge init` 还会把 Forge 的 hooks 和 permissions 合并到**全局**的 -`~/.claude/settings.json`,因此在写入之前会先声明这次合并。该合并是幂等的、由标记保护的, -永远不会覆盖用户自己的条目。 - -### Init 参数 - -| 参数 | 作用 | -| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--profile ` | 为本仓库选择策略 profile。接受 `minimal` 或 `standard`(默认)。无效的值会在任何搭建、`.forge/` 写入或合并动作之前中止。 | -| `--no-settings` | 完全跳过全局 `~/.claude/settings.json` 的合并——只写入仓库内的配置。 | -| `--remove-settings` | 撤销一次过往的 settings 合并。Forge 形状的 hooks、permissions、statusline 以及 `_forge` 标记会被移除;会先写入一份带时间戳的备份,你自己的条目会被保留。也会被 `install.sh --uninstall` 调用。 | -| `--settings-only` | 只合并全局 settings——不动仓库。被 `install.sh` 用来接线 hooks 和 permissions。 | - -如果 settings 合并被拒绝或出错,`forge init` 会以 exit 1 失败,并把原因写到 stderr,而不是报告成功。 - -### 策略 profile - -`--profile` 选择的规则集会被 `forge sync` 编译进每个工具的原生配置。只支持两个 profile: - -- **`standard`**(默认)——完整的一套:共享记忆规则、影响分析,以及完整的护栏 hook 集合。 -- **`minimal`**——面向小仓库或贡献者 fork 的更精简规则集。 - -旧名 `web-app`、`backend-service`、`library` 和 `regulated` 已被弃用,只是 `standard` 的别名。 -它们仍然可用:`forge init` 会警告一次、以 `standard` 存储,已经持有旧名的配置会按 standard 同步。 -新仓库应直接使用 `standard`。任何其他值都视为无效,会在 Forge 触及仓库之前中止。 - -```bash -forge init --profile minimal # 更精简的规则集 -forge init --no-settings # 只写仓库内配置,跳过全局合并 -forge init --remove-settings # 撤销一次过往的全局合并 -``` - -## `forge sync` - -把规范源重新编译为每个工具的原生配置文件。 - -```bash -forge sync -``` - -幂等——只会重写发生变化的部分。编辑 `source/rules.json` 或仓库内的 `.forge/rules.json` 之后运行它。 - -## `forge doctor` - -对已安装工具、护栏、MCP 授权和配置漂移做健康检查。 - -```bash -forge doctor -``` - -在工具、护栏、MCP 接线、配置漂移与更新状态上给出通过/失败结果。所有路径都是 fail-open。当配置了自定义 gateway 时,一条 **gateway models** 行会打印解析出的 `tier → model` 映射。 - -## `forge catalog` - -Start Here——列出每一个工具、crew 与护栏,并附一句话说明它们的用途。 - -```bash -forge catalog -``` - -## `forge docs` - -文档 ↔ 代码漂移。 - -```bash -forge docs check # 注册表对账——命令、环境变量、MCP 工具、CHANGELOG -forge docs sync # diff 驱动的过期文档清扫 -``` - - - 当命令、环境变量、MCP 工具或 CHANGELOG 与代码发生漂移时,`docs check` 会让 CI 失败。`docs sync` 会扫过 diff 并报告 UPDATED / STALE / VERIFIED-UNAFFECTED。 - - -## `forge update` - -在三种安装模式下进行自更新。 - -```bash -forge update # 应用更新(git checkout 或 npm/copy 安装) -forge update --check # 报告是否有更新可用 -forge update --to # 锁定或回退到特定版本 -``` - -所有路径都是 fail-open——离线、无上游或 detached HEAD 都会返回 “unknown”,绝不会报错。`FORGE_NO_UPDATE_CHECK=1` 可以让 doctor 的提示保持静默。 diff --git a/mintlify/zh-Hans/cli/memory.mdx b/mintlify/zh-Hans/cli/memory.mdx deleted file mode 100644 index 78eea04..0000000 --- a/mintlify/zh-Hans/cli/memory.mdx +++ /dev/null @@ -1,103 +0,0 @@ ---- -title: "Memory 命令" -description: "跨会话与团队记忆:cortex、recall、remember、brain、ledger、reuse、handoff 和 decide——全部汇聚到携证 ledger 上。" ---- - -Memory 分组管理跨会话与团队记忆。它们都汇聚到 `.forge/ledger/` 下的携证 ledger 上。相关模型请见 [携证记忆](/zh-Hans/concepts/proof-carrying-memory)。 - -## `forge cortex` - -自我纠错的项目记忆——从更正中挖掘出的经验。 - -```bash -forge cortex status # 学到了什么 -forge cortex why # 为什么这条经验在这里适用 -``` - -## `forge recall` - -管理跨会话的个人记忆。 - -```bash -forge recall list # 由 recall-load 护栏在下一次会话中注入的事实 -forge recall add "db port" "Postgres is on 5433 here, not 5432" -forge recall consolidate # 汇总(建议性,人工可复核) -``` - -## `forge remember` - -给本仓库的可移植记忆添加一条持久的、可提交到仓库的事实。 - -```bash -forge remember "" -``` - -## `forge brain` - -显示或重建可移植的项目记忆索引。 - -```bash -forge brain # 显示索引 -forge brain --rebuild # 重建索引 -``` - -## `forge ledger` - -携证记忆——内容寻址的主张存储。 - -```bash -forge ledger stats # 本仓库知道什么,按类别与信任等级列出 -forge ledger verify # 重新校验主张处于范式 -forge ledger show # 一条主张及其证据 -forge ledger blame # 谁写下的、每一次裁决结果、按作者划分的信任度 -forge ledger query "" # 按相关性检索 -forge ledger ratify # 人工接受 -forge ledger retract # 给一条主张打上墓碑 -forge ledger merge # 无冲突并入队友的 ledger -forge ledger import # 回填历史到 ledger 中 -``` - -加上 `--personal` 使用每用户的 ledger。 - -## `forge reuse` - -携证代码缓存——只在其证据仍然成立时才提供。 - -```bash -forge reuse query "" # 你已拥有的、已验证的代码 -forge reuse mint "" --file # 把一个产物加入缓存 -forge reuse stats # 缓存统计 -``` - -## `forge handoff` - -有边界的会话快照——重写 `.forge/state.md`,在每次会话开始时被重新注入。 - -```bash -forge handoff "" --next "" -``` - -## `forge decide` - -仅追加的决策日志——`.forge/decisions.md` 中的 `D-####` 精简 ADR 条目。 - -```bash -forge decide " — " -forge decide # 在重新决策前先读一读日志 -``` - -## `forge know` - -把一条事实路由到其正确的存储归宿——判断一段知识应放在 `recall`、`remember`/`brain`、决策或 cortex 经验中,并把它归档到那里。 - -```bash -forge know "" -``` - -## `forge deja` - -相似过往工作查询——在 ledger 里浮现出与你即将开始的工作相似的历史,让你复用现有的证明而不是重新生成。 - -```bash -forge deja "" -``` diff --git a/mintlify/zh-Hans/cli/overview.mdx b/mintlify/zh-Hans/cli/overview.mdx deleted file mode 100644 index d70997a..0000000 --- a/mintlify/zh-Hans/cli/overview.mdx +++ /dev/null @@ -1,67 +0,0 @@ ---- -title: "CLI 概览" -description: "全部 forge 命令按 Core、Memory、Substrate、Quality、Config 五组梳理，并附上控制强制策略、命令输出与秘密再编辑的环境变量，包括 FORGE_ENFORCE、FORGE_GUARD_STRICT 与 FORGE_VERBOSE。" ---- - -`forge` 命令面被定义为数据(`src/commands.js`),并由 `forge docs check` 与文档对账,因此一个命令无法在不被文档察觉的情况下上线或消失。命令分为五组。 - - - - 引导与维护:`init`、`sync`、`doctor`、`catalog`、`docs`、`update`。 - - - 跨会话与团队记忆:`cortex`、`recall`、`remember`、`brain`、`ledger`、 - `reuse`、`handoff`、`decide`。 - - - 行动前关卡及其各阶段:`substrate`、`preflight`、`route`、`impact`、 - `scope`、`context`、`anchor`、`diagnose`、`imagine`、`lean`。 - - - 验证与安全:`verify`、`scan`、`spec`、`taste`、`uicheck`、`harden`。 - - - 提供方、成本、仪表盘、品牌、atlas、stack:`config`、`cost`、`dash`、`brand`、 - `atlas`、`stack`。 - - - -## 约定 - -- **默认建议性。** 设置 `FORGE_ENFORCE=1` 可把基座变成对最强信号的硬阻断 - (空洞的提示、无法装配出必需上下文、爆炸半径超过默认的 25 文件阈值)。 -- **默认安静。** 每个命令的 `Forge — …` 标题只是品牌装饰,藏在 - `--verbose` / `FORGE_VERBOSE` 后面;命令会先输出结果。 -- **管道友好的输出。** 被管道时输出纯文本;在 TTY 上会加上品牌配色和置信度进度条。`NO_COLOR` 关掉颜色,`FORCE_COLOR=1` 强制打开。 -- **`--json`** 在基座和大多数分析命令中可用,便于脚本使用。 - -## 环境变量 - -| 变量 | 作用 | -| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| `FORGE_ENFORCE=1` | 把基座最强的建议性信号变成硬阻断。 | -| `FORGE_GUARD_STRICT=1` | 把 secret 脱敏器的 `DEGRADED` 警告升级为阻断性退出。默认情况下,脱敏失败会向 stderr 打印 `secret redaction DEGRADED` 并放行输出;严格模式会拒绝输出任何脱敏器无法完全清洗的内容。适合在 CI 或共享机器上使用,那里一行未脱敏的内容比一次失败的命令更糟。 | -| `FORGE_NO_UPDATE_CHECK=1` | 让 `forge doctor` 中 “落后上游若干 commit” 的提示保持静默。 | -| `FORGE_NO_HINT=1` | 关闭那条一次性、提示你运行 `forge init` 的初始化提示。 | -| `FORGE_VERBOSE=1` | 显示默认被隐藏的每命令横幅(`Forge — …`)。 | -| `FORGE_EMBED=1` | 为 memory recall 启用 embedding 分层(MinHash 仍是零依赖的默认)。 | -| `FORGE_LEDGER_ONLY=0` | 应急开关。仅 ledger 现为默认——记忆只存放在 `.forge/ledger` 中，旧的 `lessons/*.md` 与 fact 文件不再写入。设为 `0` 可恢复旧的文件存储。 | - - - 运行 `forge --help` 查看始终最新的命令列表,或 `forge catalog` 查看每个工具、crew 与护栏的 Start-Here 索引及一句话说明。 - - -## 更新的命令与标志 - -这些命令和参数均已可用。它们记录在各自的分组页面里,并在正文标注: - -| 命令 / 参数 | 分组 | 作用 | -| ---------------------- | -------- | ------------------------------------------------- | -| `forge know` | Memory | 把一条事实路由到它正确的存储归宿。 | -| `forge deja` | Memory | 相似的过往工作查询。 | -| `forge precommit` | Quality | commit 级别的验证关卡。 | -| `forge radar` | Quality | 依赖时效性环。 | -| `forge report` | Config | 生成本仓库 Forge 状态的静态 HTML 报告。 | -| `forge tools` | Config | 主用工具选择 + gitignore 接线。 | -| `forge verify --deep` | Quality | 多视角共识验证。 | -| `forge update --to` | Core | 锁定或回退到特定版本。 | diff --git a/mintlify/zh-Hans/cli/quality.mdx b/mintlify/zh-Hans/cli/quality.mdx deleted file mode 100644 index 887f7cb..0000000 --- a/mintlify/zh-Hans/cli/quality.mdx +++ /dev/null @@ -1,92 +0,0 @@ ---- -title: "Quality 命令" -description: "验证与安全:verify、scan、spec、taste、uicheck 和 harden。" ---- - -Quality 分组是验证与安全的入口。这些命令如何组合,请见 [验证关卡](/zh-Hans/concepts/verification-gates)。 - -## `forge verify` - -独立验证关卡——测试 + 幻觉符号 + 溯源。 - -```bash -forge verify -forge verify --deep # 多视角共识 -``` - -`forge verify --deep` 报告的是四态 `status`,而不是简单的通过/失败: - -| Status | 含义 | -| ---------------- | --------------------------------------------------------------------------------- | -| `PASS` | 每个视角都一致通过,**并且**核心 `forge verify` 的测试状态也是 `PASS`。 | -| `FAIL` | 至少有一个视角报告了真实的失败。 | -| `INCOMPLETE` | 某个视角未能完成(超时、崩溃、缺依赖)——视为未被证明。 | -| `NOT_CONFIGURED` | 本仓库没有接入任何视角——实际上什么都没检查。 | - -只有 `PASS` 才算“已验证”。当底层 `forge verify` 的测试状态不是 `PASS` 时,`--deep` 会有意拒绝把共识提升为 `PASS`,因此一次绿色的 deep 运行必然意味着一次绿色的基础运行。 - -## `forge scan` - -技能关卡——在安装前审查一个 skill 或 MCP 服务器是否存在注入 / RCE / 数据外泄风险。 - -```bash -forge scan -``` - -## `forge spec` - -规约即契约——init(OpenSpec)、lock 与漂移检查。 - -```bash -forge spec init -forge spec lock -forge spec check -``` - -## `forge taste` - -为本仓库启用一种 UI 品位工具(不带参数会列出选项)。 - -```bash -forge taste # 列出配置 -forge taste # brutalist · corporate · editorial · minimalist · playful -``` - -写入 `DESIGN.md`,并参数化 `uicheck design` 关卡的阈值。 - -## `forge uicheck` - -确定性 UI 检查。 - -```bash -forge uicheck contrast # WCAG 对比度 -forge uicheck fingerprint # 确定性设计指纹 -forge uicheck design # slop 距离 + 合规关卡 -forge uicheck visual # 基于 Playwright 的渲染检查(可选层) -``` - -## `forge harden` - -接线安全控制——gitleaks pre-commit + 沙箱设置。 - -```bash -forge harden -``` - -## `forge precommit` - -commit 级别关卡——在 commit 时运行验证下限,让部分或未验证的工作在落地前被拦下。 - -```bash -forge precommit -``` - -## `forge radar` - -依赖时效性环——把项目依赖按时效性分组,让陈旧或漂移的依赖在造成问题之前显形。 - -```bash -forge radar -``` - -如何读懂这些环,请见 [保持依赖时效性](/zh-Hans/guides/radar-deps) 指南。 diff --git a/mintlify/zh-Hans/cli/substrate.mdx b/mintlify/zh-Hans/cli/substrate.mdx deleted file mode 100644 index 9e43c86..0000000 --- a/mintlify/zh-Hans/cli/substrate.mdx +++ /dev/null @@ -1,99 +0,0 @@ ---- -title: "Substrate 命令" -description: "行动前关卡及可单独调用的各阶段:substrate、preflight、route、impact、scope、context、anchor、diagnose、imagine 和 lean。" ---- - -Substrate 分组就是行动前关卡。`forge substrate` 把其余各阶段合成一次裁决;每个阶段也都可以单独调用。管道细节请见 [行动前关卡](/zh-Hans/concepts/pre-action-gate)。 - -## `forge substrate` - -一次行动前关卡:假设、路由、影响、范围、记忆、验证。 - -```bash -forge substrate "" -forge substrate "" --json -``` - -若返回 `okToProceed:false`,在编辑前先问它返回的 `assumption.questions`。 - -## `forge preflight` - -假设检查——任务点名的东西中,仓库还没定义的部分。 - -```bash -forge preflight "" -``` - -## `forge route` - -为任务推荐能胜任的最便宜模型。 - -```bash -forge route "" -forge route gateway # 生成 LiteLLM gateway 配置 -``` - -## `forge impact` - -基于 atlas 图,预测一个符号或文件的爆炸半径。 - -```bash -forge impact -``` - -## `forge scope` - -把文件拆分为独立聚类——外加你未点名的耦合文件。 - -```bash -forge scope -``` - -## `forge context` - -有预算的上下文装配 + 完整性关卡——一次编辑必须知道的信息。 - -```bash -forge context "" -``` - -通过对预测编辑集的 set-cover 装配一份有预算的上下文,应用一条压缩阶梯,并报告计算出的缺失集。 - -## `forge anchor` - -目标漂移检查——你实际的(git)改动是否仍在既定目标上? - -```bash -forge anchor set "" # 让目标跨会话持久保留 -forge anchor show -forge anchor clear -``` - -## `forge diagnose` - -死循环检查——记录一次失败;同一签名出现 3 次将会生成一份诊断 + 升级建议。 - -```bash -forge diagnose "" -``` - -## `forge imagine` - -后果模拟——为任务给出预测的破坏点 + 最小 dry-run 测试套件。 - -```bash -forge imagine "" -forge imagine "" --run # 在沙箱中执行这套最小测试 -``` - -## `forge lean` - -范围最小性(M5)——衡量 diff 的足迹与任务要求之间的差距。 - -```bash -forge lean -``` - - - `route`、`impact`、`scope`、`context`、`anchor` 和 `lean` 各阶段都会在 `forge substrate` 内部运行。想只拿其中一个信号时,单独调用它们。 - diff --git a/mintlify/zh-Hans/concepts/config-compiler.mdx b/mintlify/zh-Hans/concepts/config-compiler.mdx deleted file mode 100644 index 45df2a2..0000000 --- a/mintlify/zh-Hans/concepts/config-compiler.mdx +++ /dev/null @@ -1,84 +0,0 @@ ---- -title: "四层配置编译器" -description: "只写一次基座;forge sync 把它编译成每个工具的原生配置。四层是大脑的表达方式;编译器是它的交付方式。" ---- - -只写一次基座。`forge sync` 会把这份源编译成每个工具的原生配置。四层是 _大脑如何被表达_;编译器是 _它如何被交付_。 - -```mermaid -flowchart TD - S["source/ · rules.json · substrate.json · mcp.json"] -->|"forge sync — content-hash + DO-NOT-EDIT headers"| N["native configs · CLAUDE.md · AGENTS.md · .cursor · .gemini · .aider"] - S -. configures .-> L - subgraph L["the four layers"] - direction LR - T["tools · model-invoked skills"] - C["crew · isolated sub-agents"] - G["guards · deterministic hooks"] - M["mcp · atlas + substrate server"] - end -``` - -## 一份源,多个生成器 - -规则**只写一次**(`source/rules.json`);一个确定性编译器(`forge sync`)以每个工具的原生格式发出配置,并带内容哈希头,让漂移可检测,重跑是无操作。任何规则都不会被写第二遍。规范源是三个文件: - -| 源文件 | 存放内容 | -| ----------------------- | -------------------------------------------------------------------- | -| `source/rules.json` | 规范的工程规则(git、测试、安全、风格)。 | -| `source/substrate.json` | 认知基座的默认值——阈值、路由、LLM 参数。 | -| `source/mcp.json` | 生成到各工具中的 MCP 服务器定义。 | - -## 四层 - -每一层都有品牌命名,并跨工具发出。 - - - - `~/.forge/tools/` → `~/.claude/skills/`。遵循 - `SKILL.md` 标准(`name` + `description` frontmatter)的模型可调用 skill。 - - - `~/.forge/crew/` → `~/.claude/agents/`。上下文隔离的子代理,如 scout、verifier 和 frontend-verifier。 - - - `~/.forge/guards/` → `settings.json` hooks。**唯一 _强制执行_ 而非建议的一层。** 一条 guard 是模型无法漂移出的确定性钩子。`CLAUDE.md` 里的散文规则会被确认,然后在压缩后遗忘;guard 不会。每一条可强制的不变式都应放在这里。 - - - Forge 附带一个 stdio 服务器(`src/cortex_mcp.js`),暴露 19 个 MCP 工具:基座检查 - (`substrate_check` / `predict_impact` / `assumption_gate` / …)、记忆读 _与_ 写(`forge_remember`、ledger ratify/retract)以及运维/健康接口。 - - - -横切关注点贯穿四层:**atlas**(代码图)、**lean** -(极简性——同时以工具和 Stop-guard 的形式发布,无论模型是否调用它,都会生效)与 **recall**(记忆)。 - -## Guard 胜过散文 - -模型有可能漂移出的规则以散文形式存在;它 **绝不** 能违反的规则以 guards(确定性 shell 钩子)存在。guard 不会在上下文压缩后被遗忘。 - - - 把每一条可强制的不变式从 `CLAUDE.md` 迁到 guard;让散文保持稀薄。这是 Forge 设计中最重要的一条纪律。 - - -## 已核实的跨工具生成矩阵 - -Forge 为**九个工具**生成配置,并为 Roo Code 和 VS Code 提供一台 MCP 服务器。每一行都对照厂商文档核实过。 - -| 工具 | 原生目标 | Forge 如何生成 | -| ------------------ | ---------------------------------------------------------------- | --------------------------------------------------------------------- | -| **Claude Code** | `CLAUDE.md`(+ `.claude/rules/*.md`、`settings.json`) | 首行为 `@AGENTS.md` 的薄 `CLAUDE.md`;guards → settings | -| **Codex** | 原生 `AGENTS.md`(32 KiB 上限) | 根目录的规范 `AGENTS.md` **就是**源 | -| **Cursor** | `AGENTS.md` + `.cursor/rules/*.mdc` | 扁平规则用 `AGENTS.md`;需要作用域时用 `.mdc` | -| **Gemini** | `GEMINI.md`,或通过 `context.fileName` 选用 `AGENTS.md` | 写入 `.gemini/settings.json` 以避免第二份副本 | -| **Aider** | 通过 `.aider.conf.yml` 的 `read:` 读取 `CONVENTIONS.md` | 生成带 `read: AGENTS.md` 的 `.aider.conf.yml` | -| **Copilot** | 根 `AGENTS.md` + `.github/copilot-instructions.md` | 依赖根 `AGENTS.md`;可选的 `.github` 指针 | -| **Windsurf/Devin** | 自动发现的 `AGENTS.md`(上限 6k/12k 字符) | 根 `AGENTS.md` 保持在上限之下;区分 `.windsurf` 与 `.devin` | -| **Zed** | 包含 `AGENTS.md` 在内的一份优先级列表中的首个匹配 | 生成 `AGENTS.md`;doctor 会标出任何被遮蔽的旧文件 | -| **Continue** | `.continue/rules/*.md` + `.continue/mcpServers/*.yaml` | 生成一份规则文件外加 Forge MCP 服务器配置 | - -Roo Code 与 VS Code 通过 `forge init` 获得 Forge MCP 服务器 -(`.roo/mcp.json`、`.vscode/mcp.json`),而不是规则文件。 - - - **字符上限是真的。** Codex 会在 32 KiB 处截断,Windsurf 在 6k/12k 处截断。`forge sync` 会强制执行一个源大小预算,以免配置被悄悄截断。 - diff --git a/mintlify/zh-Hans/concepts/cross-session-memory.mdx b/mintlify/zh-Hans/concepts/cross-session-memory.mdx deleted file mode 100644 index 7b6a789..0000000 --- a/mintlify/zh-Hans/concepts/cross-session-memory.mdx +++ /dev/null @@ -1,76 +0,0 @@ ---- -title: "跨会话记忆" -description: "会话锚定、完成关卡、handoff 快照与决策日志——用来终结会话失忆和部分完成的那一层。" ---- - -这一层要终结的两种失效模式:**部分完成**(代码变了,但依赖它的产物没跟上)和 **会话失忆**(下一次会话又要重新假设这一次已知的东西)。指令能提升正确行为的 _概率_;确定性钩子保证一个 _下限_。 - -## 会话锚定 - -在 `SessionStart`(`src/session.js`)时,Forge 会记录一次 `HEAD`、修剪一周前的会话产物,并注入一份新的定位信息: - - - - 从过往更正中挖出的 cortex 经验。 - - - 声明的目标,以便据此度量漂移。 - - - 上一次会话写下的有边界的 `.forge/state.md`。 - - - 最近的提交与未提交改动——作为证据,而非先验。 - - - -一个新会话基于证据、而非先验,来定位自己。 - -## 完成关卡 - -Stop 路径上唯一有权作答的 guard 是 `completion-gate.sh` -(`src/gate.js`)。它同步运行;挖掘经验的 `cortex.sh stop` 保持分离,永远不会阻塞。 - -变更集是**会话范围**的:提交者时间在会话开始之后的提交所涉及的文件,加上工作区的改动,再减去在 `SessionStart` 时快照的“脏文件”——因此已存在的编辑、分支切换和 `git pull` 永远不会被算到代理头上。 - - - 如果代码动了、却没有跟进文档或状态产物,该关卡会**拦下一次**,并以修复清单作为原因。其他情况一律放行,所有内部错误也放行(fail-open)。`FORGE_STOPGATE=0` 可关闭它。 - - -对于改动了代码的会话,该关卡还要求提供**测试证据**——要么在会话 diff 中包含一个测试文件,要么针对当前改动重新跑一次通过的 `forge verify`。仅有一次 `forge handoff` 快照,已经不足以清掉关卡中“代码变更”这一分支。 - -修复清单指向能把工作收尾的工具: - -```bash -forge verify # 为代码变更记录测试证据 -forge docs sync # 扫过 diff,找出过期的文档提法 -forge handoff "" --next "" # 写下有边界的会话快照 -forge decide " — " # 记录一次选择,让下一次会话不再重新决定 -``` - -## Handoff 与决策 - -两种存储让知识跨会话延续: - -| 存储 | 语义 | -| --------------------- | ------------------------------------------------------------------------------------ | -| `.forge/state.md` | 有边界的**重写**(快照)——加载成本永远保持 `O(bound)`。 | -| `.forge/decisions.md` | 仅追加的**精简 ADR**(`D-####`),带一份机器可读的决策 ledger 副本。 | - -两者在写入时都拒绝密钥。`state.md` 会在每次会话开始时被重新注入; -`decisions.md` 会在重新决定过往会话已定的事之前先被读到。 - -```bash -forge handoff "" --next "" -forge decide " — " -forge decide # 在重新决策之前先读一读日志 -``` - -## diff 驱动的文档清扫 - -`forge docs sync` 回答这个由 diff 决定形状的问题:变更的标识符 -(来自新增 _与_ 删除行中的路径、定义与被调用符号)对每个文档产物做扫描 → UPDATED / STALE(带 file:line 命中)/ VERIFIED-UNAFFECTED,并记录原因。它是纯报告器;真正咬人的牙齿由完成关卡提供。 - - - `recall` 和 `cortex` 仅仅是文件与提示级别的记忆——**不是** 权重级学习。合并操作是一个可能产生幻觉的总结器,所以它保持建议性、人工可复核,并且不包含密钥。 - diff --git a/mintlify/zh-Hans/concepts/model-routing.mdx b/mintlify/zh-Hans/concepts/model-routing.mdx deleted file mode 100644 index 40b8fa6..0000000 --- a/mintlify/zh-Hans/concepts/model-routing.mdx +++ /dev/null @@ -1,63 +0,0 @@ ---- -title: "模型路由" -description: "一份确定性、可 diff 的评分表在分发之前挑选出能胜任的最便宜模型层——外加针对自托管 gateway 的安全兜底重映射。" ---- - -Forge 在分发**之前**为任务推荐能胜任的最便宜模型,依据是一份你可以在仓库里读到的确定性评分表(`src/model_tiers.json`)。与在代理内部于请求时刻做决定的 gateway 不同,路由决定在 git 中是可见且可 diff 的。 - -## 推荐一个 tier —— `forge route` - -```bash -forge route "" # 任务的最便宜可胜任模型 tier -forge route gateway # 生成 LiteLLM gateway 配置 -``` - -推荐依据是一个基于样本 k-NN 的数学计算,在一份标注库(英语 + Hinglish 行)上、以重叠相似度作为度量,并带一个置信度阈值——不是关键词查表。 - - - 从推荐的 `route.tier` 开始,只在外部校验者失败后升级,绝不预先升级。这样既压低支出,又不会在任务确实需要时限制能力。 - - -## 先意图,后 tier - -路由与意图识别(`src/intent.js`)共享同一套数学:一段提示通过同一个样本 k-NN 估计器映射到一个意图。注意二者使用不同的停用集——route 把泛用动词(`fix` / `add` / `build`)视为复杂度噪声,而这些动词恰是意图的信号。 - -## Tier 表 - -tier 表(`src/model_tiers.json`)按家族(haiku / sonnet / opus / fable)固定了 Anthropic 的公开模型 ID。文档里的价格通过文档检查与该文件对账,因此正文和表格不会漂移。 - -## 自托管 gateway 的重映射 - -自托管的 LiteLLM 或代理 gateway 会使用它自己的模型名称,所以直接把 stock ID 发过去会 404。当配置了非默认的 gateway base URL 时,Forge -(`src/gateway_model_map.js`)会**每个进程只**取一次 `GET /v1/models`,并把每个已宣告的 id 对每个 tier 的家族打分: - - - - 家族关键词(haiku / sonnet / opus / fable)必须匹配——它是硬闸。 - - - 在同家族内部,tier 名称 token 的 `setOverlap` 系数选出最佳匹配。 - - - 平局时,更接近规范名的 id 胜出。 - - - - - 重映射**仅**在解析出的 id 是 _stock_ ID 时才咨询 gateway——显式的 - `.forge/providers.json` 别名或 `ANTHROPIC_MODEL` 覆写永远不会被触及。它在没有 gateway、`/v1/models` 不可达或家族不匹配时安全退回到 stock ID,因此直连 `api.anthropic.com` 的用户是逐字节相同的。 - - -`forge doctor` 的 **gateway models** 行会打印解析出的 `tier → model` 映射以便核对。 - -## 提供方与成本 - -```bash -forge config # 展示 / 切换 / 添加提供方,设置默认模型 -forge cost # 真实的每日花销 -forge cost --stages # 实测的每阶段成本系数 -``` - - - `forge cost --stages` **仅报告已实测的阶段**——没有事件的阶段会显示 “no data”,绝不使用默认值。一个数字在被测量之前只是一个假设。 - diff --git a/mintlify/zh-Hans/concepts/pre-action-gate.mdx b/mintlify/zh-Hans/concepts/pre-action-gate.mdx deleted file mode 100644 index b4220c9..0000000 --- a/mintlify/zh-Hans/concepts/pre-action-gate.mdx +++ /dev/null @@ -1,86 +0,0 @@ ---- -title: "行动前关卡" -description: "forge substrate 在模型编辑代码之前跑一趟有序的检查,并返回一次裁决——假设、路由、影响、范围、记忆与验证。" ---- - -**认知基座**——在模型编辑代码 _之前_ 运行的那一层。`forge -substrate ""`(以及 MCP 工具 `substrate_check`)运行一趟有序的检查,并返回一次裁决。它把各阶段——`preflight`、`route`、`atlas`、`impact`、`reuse`、`context`、`scope`、`lean`、`anchor`、`verify`——合成一份行动前契约,这些阶段也都能单独调用。 - -```mermaid -flowchart TD - RE["referenced entities"] --> INTAKE - subgraph INTAKE["intake"] - direction LR - PF["preflight · assumption gap"] --> RT["route · cheapest tier"] - end - INTAKE --> ANALYSIS - subgraph ANALYSIS["analysis"] - direction LR - AT["atlas · code graph"] --> IM["impact · blast radius"] --> PT["predict · failing tests"] --> RU["reuse · cache hit?"] - end - ANALYSIS --> SAFETY - subgraph SAFETY["safety + fit"] - direction LR - CX["context · completeness gate"] --> SC["scope · coupled files"] --> ME["memory · recall + lessons"] --> MN["minimality · lean footprint"] --> GA["goal-anchor · drift check"] - end - SAFETY --> VD["verdict"] -``` - -## 三个阶段 - - - - **preflight** 找出假设缺口——任务点名却在仓库里未定义的东西。**route** 挑出能胜任的最便宜模型 tier。 - - - **atlas** 读取代码图,**impact** 计算爆炸半径,**predict** 指出可能失败的测试,**reuse** 检查是否命中已验证的缓存。 - - - **context** 运行完整性关卡,**scope** 浮现耦合文件,**memory** 注入 recall + 经验,**minimality** 衡量精简足迹,**goal-anchor** 检查漂移。 - - - -## 爆炸半径 - -**爆炸半径**——一次编辑被预测会影响到的文件集,从代码图中读出。`forge impact` 计算它;管道会在模型触碰任何东西之前把它浮现出来。 - -```bash -forge impact verifyToken # 一个符号的预测受影响文件 -forge impact src/auth.js # ……或一个文件的 -``` - -## 默认建议性 - -裁决**默认是建议性的**——它报告,不阻断。设置 -`FORGE_ENFORCE=1` 可把最强信号变成硬阻断: - - - - preflight 找不到可执行意图——任务描述不足。 - - - 完整性关卡无法覆盖预测的编辑集。 - - - 受影响集超过默认约 25 个文件的阈值。 - - - -其他一切都保持为可被人工覆写的警告。 - - - 在 Claude Code 上,整个关卡通过 `UserPromptSubmit` 钩子在**每次提示自动**运行——对干净任务保持安静。`forge substrate "" --json` 给出可脚本化的机器可读裁决。 - - -## 运行它 - -```bash -forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" -forge substrate "" --json -``` - -如果裁决是 `ASK FIRST`,在编辑前先问它返回的 `assumption.questions` ——不要对一个描述不足的任务瞎猜。从推荐的 `route.tier` 开始,只在外部校验者失败后升级,绝不预先升级。 - - - 记忆阶段从携证 ledger 中读取。 - diff --git a/mintlify/zh-Hans/concepts/proof-carrying-memory.mdx b/mintlify/zh-Hans/concepts/proof-carrying-memory.mdx deleted file mode 100644 index 71316e7..0000000 --- a/mintlify/zh-Hans/concepts/proof-carrying-memory.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "携证记忆" -description: "每一条被存储的事实、经验或复用产物,都是一条自带证据的主张——只有当独立裁决者把其置信度抬到下限之上时才被信任。" ---- - -**携证记忆(PCM)**——每一条被存储的事实、经验或复用产物,都是一条自带证据的 _主张_。它只有在独立裁决者(测试、CI、人工接受/回退)把它的置信度抬到某个下限之上时才被信任。错误的经验会衰减出去,而不是固化下来。 - - - “携证记忆” 是我们对 **带证据引用、内容寻址记忆** 的称呼——主张以其内容哈希作为地址,并与背书它的裁决结果相互链接。“证明”指的是这条证据链加上置信度规则,**并不是形式化的、机器可校验的证明**;整条链路里没有定理证明器。 - - -## 一个存储,多个写入者 - -所有记忆子系统都汇聚到同一个存储。`recall`、`remember`/`brain`、`cortex` 经验、`reuse` 产物和死循环 `diagnose` 结果都会把内容寻址的主张写入 `.forge/ledger/`。 - -```mermaid -flowchart LR - subgraph EV["local events"] - direction TB - E1["recall / remember"] - E2["cortex lesson"] - E3["reuse mint"] - E4["diagnose"] - end - EV -->|"content-addressed claims"| LG["(.forge/ledger)"] - O["independent oracles · tests · CI · human accept/revert"] -->|"append evidence · move confidence"| LG - TM["teammate ledgers"] <-->|"git union-merge · conflict-free"| LG - LG --> RV["merged read view · recall list · lesson inject · brain index"] -``` - -## 为什么它能无冲突地收敛 - -因为一条主张的字节是 `(kind, body, scope)` 的纯函数,每个副本都会计算出相同的身份——因此队友的 ledger 通过纯 git 无冲突地并入。 - -机制上: - -- **证据与墓碑是仅追加的**、按哈希去重的日志。 -- **置信度(`val`)** 是衰减的 Beta 后验,只由裁决者推动。 -- **合并是 join-semilattice**——经过属性测试为可交换、可结合、幂等——因此 ledger 在任意顺序下都会收敛。 - - - `forge init` 会生成 ledger 所需的 union-merge `.gitattributes` 规则;`forge - ledger merge ` 会并入任意另一棵 ledger 树。完整决策记录在 ADR-0006(携证记忆)。 - - -## 只有裁决者能推动置信度——其他任何东西都不行 - -只有独立裁决者能推动一条记忆的置信度: - - - - 覆盖该主张的一个通过测试会提升它的置信度。 - - - 一条绿色流水线是该主张仍然成立的独立证据。 - - - 显式接受或一次回退是最强的信号。 - - - -不可验证的证据会被一个封闭的 `ORACLES` 表(`src/ledger.js`)拒绝。未经复核的知识会衰减向 _不确定_,而不是被删除——休眠主张会被保留以供审计,绝不会被悄无声息地清除。 - -## Ledger 命令面 - -```bash -forge ledger stats # 本仓库知道什么,按类别与信任等级列出 -forge ledger verify # 重新校验主张处于范式 -forge ledger show # 一条主张及其证据链 -forge ledger blame # 谁写下的、每一次裁决结果、按作者划分的信任度 -forge ledger query "" # 按相关性检索主张 -forge ledger ratify # 人工接受 -forge ledger retract # 给一条主张打上墓碑 -forge ledger merge # 无冲突并入队友的 ledger -forge ledger import # 把旧存储桥接到 ledger 中 -``` - -加上 `--personal` 使用每用户的 ledger。 - -## reuse 缓存也是携证的 - -`forge reuse` 是一个携证的代码缓存。一个已生成的产物只有在其证据仍然成立时才会被再次提供——置信度在下限之上 **并且** 它在 atlas 中的依赖仍然解析得到。否则它会回退到生成路径,并在返回途中打上一条新的主张。 - -```mermaid -flowchart LR - SP["spec"] --> FP["fingerprint · MinHash + LSH"] - FP --> LD["match ladder · exact to near to adapt to miss"] - LD --> GT{"confidence >= floor AND deps resolve?"} - GT -->|"yes"| SV["serve · proof holds"] - GT -->|"miss"| GN["generate"] - GN -->|"mint claim"| MT["(.forge/ledger)"] -``` - - - MinHash 的近邻匹配在非常短的规约上偏弱。可选的 embeddings 后端 - (`FORGE_EMBED`)能改善这一点;MinHash 依然是零依赖的默认。 - diff --git a/mintlify/zh-Hans/concepts/verification-gates.mdx b/mintlify/zh-Hans/concepts/verification-gates.mdx deleted file mode 100644 index 3e02740..0000000 --- a/mintlify/zh-Hans/concepts/verification-gates.mdx +++ /dev/null @@ -1,108 +0,0 @@ ---- -title: "验证关卡" -description: "独立验证、幻觉符号标记、规约即契约与技能关卡——你能实际运行的检查,它们能减少但从不能认证正确性。" ---- - -没有可以真正跑一遍的检查,就不算 “完成”——一个测试、一个构建退出码、一张截图。Forge 的验证关卡各自多接住一次。设每任务漏率为 `1 − p`,关卡拦截率为 `c`,则静默漏失下降到 `(1 − p)(1 − c)`,而这里每一道关卡都多贡献一个 `c`。 - - - **验证是减少,不是认证。** Crew 校验者和幻觉符号标记能降低评审负担;它们并不证明代码正确。测试和人工纠正永远胜出。 - - -## 独立验证 —— `forge verify` - -一道独立关卡:它会跑仓库真实的测试、标出幻觉符号,并检查溯源。 - -```bash -forge verify # 测试 + 幻觉符号 + 溯源 -forge verify --deep # 多视角共识——多个独立检查必须一致 -``` - - - `--deep`升级为多视角共识:变更必须通过多个独立的验证视角,而不只是一个。 - - -`forge verify --deep` 报告的是四态 `status`,不是二元的通过/失败: - -- `PASS` —— 每个视角都一致通过,**并且**核心 `forge verify` 的测试状态也是 `PASS`。只有这个状态才算“已验证”。 -- `FAIL` —— 至少有一个视角报告了真实的失败。 -- `INCOMPLETE` —— 某个视角未能完成(超时、崩溃、缺依赖)。既没有被证伪,也没有被证明。 -- `NOT_CONFIGURED` —— 本仓库没有接入任何视角,`--deep` 无从检查。 - -`PASS` 蕴含基础 `PASS` 的规则是有意为之:一次绿色的 deep 共识永远不能跑在红色的基础运行前面,因此基础测试视角上的 `INCOMPLETE` 或 `NOT_CONFIGURED` 会把 deep 的结果降级到相应状态。 - -## 幻觉符号标记 —— `forge atlas has` - -`forge atlas has ` 是幻觉检查:如果模型调用了不在代码图里的符号,该关卡会把它标出来。 - -```bash -forge atlas build # 索引本仓库的符号 → .forge/atlas.json -forge atlas has useAuth # “not found” = 很可能是幻觉 -``` - -atlas 有意做成纯 JSON——Codex、Cursor、Gemini 和 Aider 都可以通过 CLI 或直接的 `jq` 消费 `.forge/atlas.json`,不需要依赖 MCP。 - -## 规约即契约 —— `forge spec` - -把行为固定到一份规约上,并检测与之的漂移: - -```bash -forge spec init # 生成一份 OpenSpec 契约 -forge spec lock # 把当前规约锁定为契约 -forge spec check # 报告与锁定契约的漂移 -``` - -## 技能关卡 —— `forge scan` - -在安装 skill 或 MCP 服务器之前,审查它是否有注入、RCE 或数据外泄风险: - -```bash -forge scan -``` - - - 扫描通过 **不是安全认证。** 内置启发式只能识别已知的攻击形态(critical)和少量高严重度的模式;通过意味着 _“未检测到 critical 特征”_,而不是 _“可以放心安装”_。永远要自己审阅源码、权限、包溯源和网络行为。**high** 严重度的发现即便不硬阻断,也不会被标记为安全。外部扫描器是可选的,除非你启用它,否则不会发起任何网络调用。 - - -## 加固 —— `forge harden` - -接线让密钥和不安全的变更进不了仓库的安全控制: - -```bash -forge harden # gitleaks pre-commit + 沙箱设置 -``` - -## commit 级别关卡 —— `forge precommit` - - - `forge precommit`是一道 commit 级别的关卡——它在 commit 时运行验证下限,让部分或未验证的工作在落地前被拦下。 - - -## 完成关卡 —— 需要测试证据 - -Stop 路径上的完成关卡(见 [跨会话记忆](/zh-Hans/concepts/cross-session-memory))不再把代理的 handoff 当作代码变更已完成的证据。对于任何触及源码的会话,该关卡要求**真实的测试证据**: - -- 在会话 diff 中改动了一个测试文件,**或者** -- 针对当前改动重新跑了一次通过的 `forge verify`。 - -单凭一次 `forge handoff` 快照无法满足该关卡——它记录的是意图,不是验证。如果两种证据都没有,关卡会以修复清单**拦下一次**: - -```bash -forge verify # 生成测试证据 -forge handoff "" --next "" # 然后再对会话拍快照 -``` - -只涉及文档、只涉及配置以及其他非代码会话不受影响——测试证据要求只在会话 diff 真正改动了代码时才会触发。 - -## UI 检查 —— `forge uicheck` - -确定性 UI 检查,前三个视角不使用 LLM 也不使用截图: - -```bash -forge uicheck contrast # WCAG 对比度 -forge uicheck fingerprint # 确定性设计指纹 -forge uicheck design # slop 距离 + 合规关卡 -forge uicheck visual # 基于 Playwright 的渲染检查(可选层) -``` - -搭配 `forge taste` 选定一个视觉方向(brutalist、corporate、editorial、minimalist、playful),并参数化 `design` 关卡的阈值。 diff --git a/mintlify/zh-Hans/guides/radar-deps.mdx b/mintlify/zh-Hans/guides/radar-deps.mdx deleted file mode 100644 index ae5f889..0000000 --- a/mintlify/zh-Hans/guides/radar-deps.mdx +++ /dev/null @@ -1,56 +0,0 @@ ---- -title: "用 radar 保持依赖时效性" -description: "forge radar 把你的依赖按时效性分组为环,让陈旧或漂移的依赖在造成问题之前显形。" ---- - - - `forge radar` 已可用。本指南描述它如何契合既有的依赖时效性纪律;运行 `forge --help` 以确认你安装的版本中是否可用。 - - -Forge 的工程规则之一是:_在添加一个依赖之前,从实时来源核实当前的最佳选项,并优先使用项目已经在用的。_ `forge radar` 让你的依赖的当下状态变得可见,好让这条规则背后有数据支撑。 - -## 思路:时效性环 - -`forge radar` 把项目的依赖按各自的时效性分入同心的**时效性环**——从中心的最新版本,向外到边缘的陈旧或漂移。读这些环是回答“我们让什么漂了?”的一种快速方式,不必手工审计每一个包。 - -```bash -forge radar -``` - -## 依赖清单从哪里来 - -Radar 依赖的清单读取逻辑,与驱动 `forge stack` 的一致——后者从依赖清单文件中检测仓库的真实技术栈: - -```bash -forge stack # 语言、框架、包管理器、真实的测试命令 -``` - -因为检测是数据驱动、且在各生态系统间安全兜底(`package.json`、 -`pyproject.toml`、`go.mod`、`Cargo.toml`、`Gemfile`、`composer.json`、`pom.xml` / -`build.gradle`、`*.csproj`),radar 可以对 `stack` 所理解的同一批清单文件推理其时效性。 - -## 在日常工作中使用它 - - - - 在添加或升级依赖之前,先跑 `forge radar` 看看哪些依赖已经在漂。 - - - 如果一个内圈里已经有一个胜任且当前的依赖,就复用它,而不是再引入一个——最贴合需求的最小改动胜出。 - - - 当你真的升级或替换了一个依赖,记录原因: - ```bash - forge decide "bump to — " - ``` - 这样未来的会话读得到这个选择,而不会重新走一遍。 - - - - - Radar 报告时效性;它不会替你升级。把它的环视为给人工决策的建议性输入——并在把变更算作 “完成” 之前,用仓库真实的测试(`forge verify`)核实任何一次升级。 - - - - 一次依赖升级之后,跑一遍 Quality 关卡——`forge verify` 和 `forge precommit`。 - diff --git a/mintlify/zh-Hans/guides/team-memory.mdx b/mintlify/zh-Hans/guides/team-memory.mdx deleted file mode 100644 index ab63111..0000000 --- a/mintlify/zh-Hans/guides/team-memory.mdx +++ /dev/null @@ -1,66 +0,0 @@ ---- -title: "用 ledger 做团队记忆" -description: "通过纯 git 无冲突地并入队友的 ledger——没有服务器,没有同步服务,只是一些按任意顺序都能收敛的文件。" ---- - -基座学到的一切——cortex 经验、`forge remember` 事实、已验证的复用产物——都作为内容寻址的主张落到一个 git 原生的 ledger(`.forge/ledger/`)里,它天生就为无冲突合并而设计。没有服务器,也没有同步服务;只是 git 里的文件。 - -## 三条命令搞定团队记忆 - - - - ```bash - forge init - ``` - 这会生成 ledger 所需的 `.gitattributes` union-merge 规则,以及其他配置。 - - - 你正常工作时,cortex 经验与 `forge remember` 事实会把主张镜像进 ledger——不需要额外执行任何命令。 - - - ```bash - git pull && forge ledger merge - ``` - 任意顺序——合并是无冲突的。 - - - -## 为什么它不会冲突 - -一条主张的字节是 `(kind, body, scope)` 的纯函数,所以每个副本对相同的知识都会算出相同的身份。合并是一个 join-semilattice——经过属性测试为可交换、可结合、幂等——因此两位队友的 ledger 无论谁先同步都会收敛到相同的状态。 - -```mermaid -flowchart LR - A["your ledger"] <-->|"git union-merge · conflict-free"| B["teammate ledger"] - A --> M["merged read view"] - B --> M - M --> R["recall list · lesson inject · brain index"] -``` - - - 相同的知识在两处独立生成,会收敛为**一条**主张,并在其溯源中保留每一位作者。 - - -## 信任与溯源 - -置信度只由独立裁决者推动——测试、CI、人工接受/回退——所以并入队友的 ledger 并不是盲目相信他们的笔记;而是并入他们的 _证据_。 - -```bash -forge ledger blame # 谁写下的主张、每一次裁决结果、按作者划分的信任度 -forge ledger stats # 合并后的视图,按类别与信任等级列出 -forge ledger verify # 确认每一条主张处于范式 -``` - -## 全团队的复用 - -一旦队友已验证的代码进入合并后的 ledger,你就可以带着它的证明来复用: - -```bash -forge reuse query "" -``` - -一次命中会指向可运行、有测试确认的代码,以及能证明它的 `forge ledger blame` ——复用它,而不是重新生成。 - - - 休眠主张会被保留以供审计,绝不删除;未复核的知识会衰减向 _不确定_,而不是被删除。ledger 是一条证据链,不是一个能悄悄丢失的缓存。 - diff --git a/mintlify/zh-Hans/guides/zero-config-onboarding.mdx b/mintlify/zh-Hans/guides/zero-config-onboarding.mdx deleted file mode 100644 index 7a177d0..0000000 --- a/mintlify/zh-Hans/guides/zero-config-onboarding.mdx +++ /dev/null @@ -1,81 +0,0 @@ ---- -title: "有引导、低配置的接入" -description: "五分钟到可用:装一次、每个仓库配一次、做一次任务,并在第二天开始看到 ledger 带来回报——是有引导、低配置,而不是零操作。" ---- - -Forge 的目标是**有引导、低配置的接入**——一个新仓库通常在大约五分钟内就能进入可用状态。装一次、每个仓库配一次、做一次任务,ledger 就会在第二天开始带来回报。(它是低配置的,不是零配置:你仍然要安装 CLI、在每个仓库里跑 `forge init`,而且部分路径依赖 Bash、Git 和 `jq`。) - -```mermaid -flowchart TD - I["forge init"] --> Cfg["every tool configured from one source"] - Cfg --> Work["you work as usual"] - Work --> Gate["substrate checks each task · ask first? · which model? · what breaks?"] - Gate --> Edit["agent edits, with guardrails"] - Edit --> Learn["cortex learns from corrections"] - Learn -.->|next task is smarter| Work -``` - -## 1. 安装(一次) - -推荐路径不需要 token 也不需要克隆: - - - -```bash Plugin -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit -``` - -```bash CLI -npm install -g @codewithjuber/forgekit -``` - - - -```bash -forge doctor # 一切都绿了吗? -``` - -## 2. 配置一个仓库(每个仓库一次) - -```bash -cd ~/your-project -forge init # 生成 AGENTS.md、CLAUDE.md、.gemini/settings.json、.aider.conf.yml…… -``` - -现在 Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf、Zed 和 Continue 都从各自的原生文件里读**同一套**规则。之后要改规则,编辑 -`source/rules.json`(或在仓库里放一份 `.forge/rules.json`),然后跑 `forge sync`。 - -## 3. 使用认知基座 - -```bash -forge substrate "" # 一次跑完 ask/route/impact/scope/reuse/context/memory/verify -forge substrate "" --json -forge impact # 单独跑爆炸半径 -``` - -如果 `forge substrate` 返回 `ASK FIRST`,在编辑前先问它返回的那些问题。 - -## 4. 用一下附加功能 - -```bash -forge atlas build # 索引本仓库的符号 → .forge/atlas.json -forge atlas query useAuth # 它在哪里定义? -forge atlas has useAuth # 它存在吗?“not found” = 很可能是幻觉 -forge recall add "db port" "Postgres is on 5433 here, not 5432" -forge catalog # 一切内容的 Start-Here 索引 -``` - -## 5. 第二天:ledger 开始学习 - -基座在第一天学到的一切——cortex 经验、被记住的事实、已验证的代码——都以主张形式落到了 `.forge/ledger/`。 - -```bash -forge ledger stats # 本仓库知道什么,按类别与信任等级列出 -forge ledger blame # 谁写下的主张、每一次裁决结果 -forge reuse query "" # 你已经拥有的、已验证的代码 -``` - - - 下一步:通过纯 git 无冲突地并入队友的 ledger。 - diff --git a/mintlify/zh-Hans/installation.mdx b/mintlify/zh-Hans/installation.mdx deleted file mode 100644 index a413e2a..0000000 --- a/mintlify/zh-Hans/installation.mdx +++ /dev/null @@ -1,98 +0,0 @@ ---- -title: "安装" -description: "一棵树上的三扇前门:插件市场、npm 全局安装,以及免注册表的 github: 安装——外加贡献者的 symlink 开发环境。" ---- - -Forge 遵循**一棵树,三扇前门**的设计:插件清单、加固过的安装器和 npm 二进制都引用同一棵 `global/` + `source/` 树。选择适合你工具的通道即可。 - -## 选择一个通道 - - - - 适用于 Claude Code 和 Codex。护栏自动接线;无需合并任何东西。 - - - 适用于任何工具。从公开 npm registry 安装的 `forge` CLI。 - - - 不需要 registry——直接从仓库安装。 - - - 克隆 + `npm link`,或运行 `bash install.sh` 使用 symlink 方案。 - - - -## 系统要求 - -- **Node.js >= 20** -- **零运行时依赖**——一切都用 Node 内置模块。可选层(`FORGE_EMBED` 嵌入、`uicheck visual` 所需的 Playwright)是可选的,不引入必需依赖。 - -## 插件市场 - -给 Claude Code 和 Codex 用的推荐路径,不需要 token 也不需要克隆: - -```bash -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit -``` - -插件通过 `${CLAUDE_PROJECT_DIR}` 接线护栏,让行动前关卡和完成关卡在后台自动生效。 - -## npm 全局安装 - -任何工具都能用,来自公开 npm: - -```bash -npm install -g @codewithjuber/forgekit -forge doctor # 一切都绿了吗? -``` - -## 免注册表的 github: 安装 - -```bash -npm install -g github:CodeWithJuber/forgekit -``` - -## 贡献者 / 本地开发 - - - -```bash npm link -git clone https://github.com/CodeWithJuber/forgekit.git -cd forgekit -npm link -``` - -```bash install.sh (symlink setup) -git clone https://github.com/CodeWithJuber/forgekit.git -cd forgekit -bash install.sh -``` - - - -安装器是加固过的:幂等、基于 symlink、有备份、且不使用 `curl | sh`。 - -## 验证 - -不论你走了哪个通道,都要确认安装成功: - -```bash -forge doctor # 工具、护栏、MCP 授权、配置漂移、更新状态 -``` - - - `forge doctor` 还会对 git checkout 用户显示一条不烦人的“落后上游 N 个 commit”提示。设置 `FORGE_NO_UPDATE_CHECK=1` 可将其静默。所有路径都是 fail-open——离线或 detached HEAD 会报告 “unknown”,绝不会报错。 - - -## 保持 Forge 最新 - -```bash -forge update --check # 报告是否有更新可用 -forge update # 应用更新(git checkout 或 npm/copy 安装) -forge update --to # 锁定或回退到特定版本 -``` - - - 前往快速开始,运行 `forge init` 与第一次基座检查。 - diff --git a/mintlify/zh-Hans/introduction.mdx b/mintlify/zh-Hans/introduction.mdx deleted file mode 100644 index faa965b..0000000 --- a/mintlify/zh-Hans/introduction.mdx +++ /dev/null @@ -1,105 +0,0 @@ ---- -title: "Forge：面向 AI 编码代理的认知基座" -description: "Forge 是每个无状态模型都缺少的认知基座——记忆、预见与护栏——以原生配置形式交付给每一个 AI 编码代理。" ---- - -**给每个 AI 编码代理一个大脑。** 大语言模型是无状态的：只有一个上下文窗口，每次调用都会清空。它对你的团队学到的东西没有记忆，对一次编辑会打破什么没有预见，也没有强制执行的护栏。Forge -（`@codewithjuber/forgekit`）就是这一层**认知基座**——在模型编辑代码 _之前_ 运行的那一层，提供带证据引用、内容寻址的记忆（我们称之为 -“携证记忆”）、启发式的影响预见与强制护栏——并配备一个**跨工具配置编译器**，把这个大脑一次性以原生配置的形式交付给每个工具。Claude -Code 是经过最深入测试的集成；其余工具也会获得原生配置和 MCP 工具，只是实际验证较少。 - - - - 跨会话与跨队友持久保留的携证记忆。每一条经验、事实与已验证的复用，都是一条自带证据的主张。 - - - 一次编辑的爆炸半径——从代码图中读出的、被预测会被触及的文件集，包括你从未点名的耦合文件。 - - - 确定性的钩子强制执行模型绝不能违反的规则。它们能挺过一次上下文压缩，而写在配置文件里的散文规则做不到。 - - - -## 问题 - -大语言模型是无状态的——一个上下文窗口，每次调用都会清空。 - -- 它**没有记忆**记住你的团队已经学到了什么。 -- 它**没有预见**知道一次编辑会打破什么。 -- 它**没有强制护栏**——散文式的规则在一次压缩后就会被遗忘。 - -而且每个工具都想要自己的配置文件（`CLAUDE.md`、`AGENTS.md`、`.cursor/rules`、 -`GEMINI.md`、MCP……）。Forge 就是那一层认知基座，补上这三样缺失的东西，同时也是把它从一份源交付到每个工具中的编译器。 - -## 核心论点 - -模型在两次调用之间无法从你的代码库学习：它的权重是冻结的，工作记忆在每次响应后都会被清空。记忆、预见和自检不能靠提示词灌进去——必须从 _外部_ 提供。这一外部层就是认知基座。形式上，推理是一个固定函数 -`y = f(x)`，调用之间没有状态；Forge 就是那个状态。 - - - - 在唯一的规范源里写下你的规则和基座默认值 - （`source/rules.json`、`source/substrate.json`、`source/mcp.json`）。 - - - `forge sync` 把这份源编译成每个工具的原生配置——九个 AI 编码工具加上 MCP——带内容哈希头，因此漂移可被检测，重新运行是无操作。 - - - `forge substrate ""` 运行一次确定性的行动前流程：假设、路由、复用、上下文、爆炸半径、范围与目标锚点。 - - - 只有独立的裁决者——测试、CI、人工的接受/回退——才能推动一条记忆的置信度，因此错误的经验会衰减出去，而不是固化下来。 - - - -## 你能得到什么 - -- **跨会话、跨队友都持久的记忆。** 每一条经验、事实与已验证的复用都是 - _携证记忆（PCM）_ ——我们对带证据引用、内容寻址记忆的称呼：一条带有其证据引用的主张，只有当独立裁决者把它的置信度抬升到某个下限之上时才被信任。“证明”指的是这条证据链，不是形式化的证明。 -- **在打破东西之前预见。** 问“修改 `verifyToken` 会打破什么？”，就能从代码图中拿到爆炸半径，包括你从未点名的耦合文件。 -- **无法被遗忘的护栏。** 确定性钩子强制执行受保护路径、成本预算和死循环检测——它们能挺过上下文压缩。 -- **端到端把工作做完。** 一次会话内只触发一次的完成关卡会拦下这样一种情况：代码动了，但文档或状态产物没跟上——并把修复清单作为答复给出。 -- **一份配置服务九个工具。** 规则只写一次；Forge 会生成每个工具的原生配置，外加给 Roo 和 VS Code 的 MCP。零运行时依赖——一个 Node CLI、纯文件放在 git 里，没有服务器。 - -## Forge 给哪些工具喂配置？ - -Forge 为**九个工具**生成配置，另外为 Roo Code 和 VS Code 提供一台 MCP 服务器： -Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf/Devin、Zed 和 Continue。 -每个工具都从各自的原生文件里读取同一份规则。 - -默认接线的 MCP 服务器只有 Forge 自己的那一台（`src/cortex_mcp.js`）——负责基座检查与记忆读取。诸如 `context7` 之类的第三方 MCP 服务器均为**按需接入**,在你运行 [`forge integrations add --yes`](/zh-Hans/cli/config#forge-integrations) 之前都不会落到磁盘上。 - -## 诚实的边界 - -Forge 到处都会声明自己的上限。 - - - Forge **减少而非消除**规则漂移。它是一层透明性和可靠性的加固，不是测试、评审或判断力的替代品。 - - -- **护栏只能强制执行能够表达为钩子的东西**（路径、格式、diff 大小、预算）。语义规则（“偏好函数式”）依然是散文形式，有时会被忽略。 -- **验证是减少，不是认证。** Crew 校验者和幻觉符号标记能降低评审负担；它们并不证明代码正确。 -- **没有权重级学习。** `recall` / `cortex` 仅仅是文件与提示级别的记忆——没有强化学习，没有微调。 -- **影响图是基于正则的近似**——保守，而不是可靠的调用图。 -- **测试和人工纠正永远胜出。** - - - Forge 目前处于 **beta**。核心（`init`、`sync`、`substrate`、`impact`、`ledger`、护栏）已经测试过并在日常使用；部分参数可能在 `1.0` 之前发生变化。 - - -## 下一步 - - - - 安装、运行 `forge init`,并让你的第一个任务过一遍基座。 - - - 四层编译器、携证记忆与行动前关卡。 - - - 每一条命令,按 Core、Memory、Substrate、Quality 和 Config 分组。 - - - 通过纯 git 无冲突地并入队友的 ledger。 - - diff --git a/mintlify/zh-Hans/quickstart.mdx b/mintlify/zh-Hans/quickstart.mdx deleted file mode 100644 index 2e1f055..0000000 --- a/mintlify/zh-Hans/quickstart.mdx +++ /dev/null @@ -1,97 +0,0 @@ ---- -title: "快速开始" -description: "安装 Forge,从同一份源生成每个工具的配置,并运行你的第一次行动前关卡——大约 60 秒。" ---- - -从零到一个配置好的仓库并跑通第一次基座检查,大约需要一分钟。 - -## 1. 安装 - - - -```bash Plugin (Claude Code / Codex) -/plugin marketplace add CodeWithJuber/forgekit -/plugin install forgekit -``` - -```bash npm (any tool) -npm install -g @codewithjuber/forgekit -``` - -```bash No registry -npm install -g github:CodeWithJuber/forgekit -``` - - - -对于 Claude Code 和 Codex,推荐走插件通道——护栏会自动接线,不需要合并任何东西。完整通道矩阵(包括开发者的 symlink 方案)见 [安装](/zh-Hans/installation)。 - -## 2. 配置一个仓库 - - - - ```bash - cd ~/your-project - forge init - ``` - 这会生成 `AGENTS.md`、`CLAUDE.md`、`.gemini/settings.json`、`.aider.conf.yml` 等——外加 ledger 所需的 `.gitattributes` union-merge 规则。现在 Claude Code、Codex、Cursor、Gemini、Aider、Copilot、Windsurf、Zed 和 Continue 都从各自的原生文件里读取**同一套**规则。 - - - ```bash - forge doctor - ``` - 对已安装工具、护栏、MCP 授权和配置漂移的通过/失败检查。 - - - 编辑 `source/rules.json`(或在仓库里放一份 `.forge/rules.json`),然后重新编译: - ```bash - forge sync - ``` - `sync` 是幂等的——只会重写发生变化的部分。 - - - -## 3. 运行行动前关卡 - -基座是在模型编辑代码 _之前_ 运行的那一层。一条命令就能跑完整个关卡: - -```bash -forge substrate "Change verifyToken in src/auth.js to require length > 20; update tests" -# → 假设裁决 · 能胜任的最便宜模型 · 预测的爆炸半径 -# (包括你未点名的文件) · 范围聚类 · 验证清单 -``` - - - 在 Claude Code 上,基座会通过 `UserPromptSubmit` 钩子**在每次提示自动**运行——仅作建议,对干净的任务保持安静。其他每个工具则会获得一条原生配置规则,外加 19 个可自行调用的 MCP 工具。 - - -如果 `forge substrate` 返回 `ASK FIRST`,在编辑之前先问它返回的那些问题。在任何有变更的改动之前,先读一读预测受影响的文件——爆炸半径。 - -```bash -forge substrate "" --json # 机器可读的裁决 -forge impact # 单独跑爆炸半径 -``` - -## 4. 探索附加功能 - -```bash -forge atlas build # 索引本仓库的符号 → .forge/atlas.json -forge atlas query useAuth # 它在哪里定义?(比 grep + 阅读更便宜) -forge atlas has useAuth # 它存在吗?“not found” = 很可能是幻觉 -forge recall add "db port" "Postgres is on 5433 here, not 5432" -forge catalog # 一切内容的 Start-Here 索引 -``` - -## 5. 第二天:ledger 开始学习 - -基座在第一天学到的一切,都以主张形式落到了 `.forge/ledger/`。这就是携证记忆——从现在开始它会带来回报: - -```bash -forge ledger stats # 本仓库知道什么,按类别与信任等级列出 -forge ledger blame # 谁写下的主张,每一次裁决结果 -forge reuse query "" # 你已经拥有的、已验证的代码 -``` - - - 阅读行动前关卡如何把各阶段合成一次裁决。 -